sinapse-ai 7.0.5 → 7.2.0

package/squads/claude-code-mastery/tasks/brownfield-setup.md

@@ -0,0 +1,322 @@
+# Task: Brownfield Project Claude Code Setup
+
+**Task ID:** brownfield-setup
+**Version:** 1.0
+**Purpose:** Set up Claude Code in an existing brownfield project, respecting established conventions and protecting critical paths
+**Orchestrator:** @project-integrator (Conduit)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** No existing workflow disrupted, deny rules protect critical paths, conventions documented
+
+---
+
+## Overview
+
+This task differs from integrate-project in that it focuses on **discovering and respecting existing conventions** rather than establishing new ones. The brownfield approach prioritizes safety: protect what exists, teach Claude the project's rules, and integrate without disrupting established workflows.
+
+```
+INPUT (project_root + critical_paths)
+    |
+[PHASE 1: CODEBASE SCANNING]
+    -> Discover frameworks, patterns, naming conventions
+    -> Identify coding style from existing code
+    -> Map project structure and architecture
+    |
+[PHASE 2: EXISTING TOOLING DETECTION]
+    -> Detect CI/CD pipelines
+    -> Detect linting, formatting, testing setup
+    -> Identify deployment workflows
+    |
+[PHASE 3: CONVENTION-RESPECTING CLAUDE.MD]
+    -> Generate CLAUDE.md that teaches Claude the project's ways
+    -> Document coding patterns found in existing code
+    -> Include project-specific terminology
+    |
+[PHASE 4: PATTERN RULES]
+    -> Create rules that encode project-specific patterns
+    -> Teach Claude about architectural decisions
+    -> Document anti-patterns to avoid
+    |
+[PHASE 5: DENY RULES FOR CRITICAL PATHS]
+    -> Identify files/directories that must not be modified
+    -> Configure deny rules in settings.json
+    -> Set up allow exceptions for specific operations
+    |
+[PHASE 6: WORKFLOW INTEGRATION]
+    -> Configure hooks for existing CI/CD
+    -> Set up pre-commit alignment with existing linters
+    -> Ensure Claude follows the team's git workflow
+    |
+OUTPUT: Brownfield integration config + protected paths + convention docs
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Auto-detect | yes | Existing project with source code |
+| critical_paths | array | User | no | Paths that must never be modified by AI |
+| team_conventions_doc | string | User | no | Path to existing coding standards doc |
+| deployment_branch | string | User | no | Branch used for deployment (default: main) |
+| legacy_areas | array | User | no | Directories with legacy code to be careful with |
+
+---
+
+## Preconditions
+
+1. Project exists with established codebase (not greenfield)
+2. Project has existing commit history (to analyze conventions)
+3. User can identify critical paths that need protection
+4. Git is initialized and functional
+
+---
+
+## Phase 1: Codebase Scanning
+
+**Goal:** Understand the project's established patterns without changing anything.
+
+### Steps
+
+1.1. Scan directory structure and build a source tree:
+
+```
+src/
+  components/     -> React components (functional, arrow functions)
+  services/       -> API service layer (class-based)
+  utils/          -> Utility functions (pure functions)
+  hooks/          -> Custom React hooks (use* naming)
+  types/          -> TypeScript type definitions
+```
+
+1.2. Analyze coding patterns from existing files:
+   - Import style (named vs default, absolute vs relative)
+   - Component patterns (functional vs class, hooks usage)
+   - Error handling patterns (try/catch vs error boundaries)
+   - Naming conventions (camelCase, PascalCase, kebab-case for files)
+   - Comment style and density
+
+1.3. Detect architectural patterns:
+   - State management approach
+   - API integration patterns
+   - Routing structure
+   - Authentication flow
+
+1.4. Build a pattern inventory:
+
+```yaml
+patterns:
+  imports: "absolute with @ alias"
+  components: "functional with arrow functions"
+  state: "Zustand stores in src/stores/"
+  api: "axios instances in src/services/"
+  naming:
+    files: "kebab-case"
+    components: "PascalCase"
+    functions: "camelCase"
+    constants: "UPPER_SNAKE_CASE"
+```
+
+---
+
+## Phase 2: Existing Tooling Detection
+
+**Goal:** Map all existing development tools and workflows.
+
+### Steps
+
+2.1. Check for CI/CD:
+   - `.github/workflows/*.yml` (GitHub Actions)
+   - `.gitlab-ci.yml` (GitLab CI)
+   - `Jenkinsfile` (Jenkins)
+   - `.circleci/` (CircleCI)
+   - `vercel.json` (Vercel)
+   - `netlify.toml` (Netlify)
+
+2.2. Check for code quality tools:
+   - `.eslintrc*` / `eslint.config.*` (ESLint)
+   - `.prettierrc*` (Prettier)
+   - `.stylelintrc*` (Stylelint)
+   - `.editorconfig` (EditorConfig)
+   - `commitlint.config.*` (Commit message linting)
+
+2.3. Check for testing:
+   - `jest.config.*` (Jest)
+   - `vitest.config.*` (Vitest)
+   - `cypress.config.*` (Cypress)
+   - `playwright.config.*` (Playwright)
+
+2.4. Document existing scripts from package.json:
+
+```yaml
+scripts:
+  dev: "next dev"
+  build: "next build"
+  test: "jest --coverage"
+  lint: "eslint src/"
+  format: "prettier --write src/"
+```
+
+---
+
+## Phase 3: Convention-Respecting CLAUDE.md
+
+**Goal:** Create CLAUDE.md that teaches Claude to write code that looks like the existing codebase.
+
+### Steps
+
+3.1. Write CLAUDE.md with emphasis on existing patterns:
+
+```markdown
+# {Project Name}
+
+## Code Standards (from existing codebase)
+- Import style: {detected pattern}
+- Component pattern: {detected pattern}
+- File naming: {detected pattern}
+- Error handling: {detected pattern}
+
+## Commands
+- `{npm run dev}` -- Start development server
+- `{npm test}` -- Run tests
+- `{npm run lint}` -- Run linter
+
+## Architecture
+{Brief description of project structure}
+
+## Critical Rules
+- NEVER modify files in {critical_paths}
+- ALWAYS follow existing patterns in neighboring files
+- When in doubt, check how similar code is written in the codebase
+```
+
+3.2. If a team conventions document exists, incorporate its rules.
+3.3. Keep under 200 lines. Move details to rules files.
+
+---
+
+## Phase 4: Pattern Rules
+
+**Goal:** Create rules that encode project-specific knowledge.
+
+### Steps
+
+4.1. Create `.claude/rules/` with pattern files:
+
+| Rule | Content |
+|------|---------|
+| `code-style.md` | Naming conventions, import patterns, file structure |
+| `architecture.md` | Layer boundaries, data flow, dependency rules |
+| `anti-patterns.md` | Things to never do in this codebase |
+| `legacy-areas.md` | Special handling for legacy code sections |
+
+4.2. Use path-based activation for context-specific rules:
+
+```markdown
+---
+paths:
+  - "src/legacy/**"
+---
+# Legacy Code Rules
+- Do NOT refactor unless explicitly asked
+- Maintain existing patterns even if suboptimal
+- Add tests before making any changes
+```
+
+---
+
+## Phase 5: Deny Rules for Critical Paths
+
+**Goal:** Protect files and directories that AI should not modify.
+
+### Common Critical Paths
+
+| Path Pattern | Reason |
+|-------------|--------|
+| `.env*` | Secrets and credentials |
+| `**/migrations/**` | Database migrations (run, don't edit) |
+| `docker-compose.prod.yml` | Production infrastructure |
+| `*.lock` | Lock files (managed by package managers) |
+| `.github/workflows/**` | CI/CD pipelines |
+| `infrastructure/**` | Infrastructure-as-code |
+
+### Steps
+
+5.1. Collect critical paths from user and auto-detection.
+5.2. Configure deny rules in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Edit(.env*)",
+      "Write(.env*)",
+      "Edit(**/migrations/**)",
+      "Edit(docker-compose.prod.yml)",
+      "Edit(.github/workflows/**)"
+    ],
+    "allow": [
+      "Read(**)"
+    ]
+  }
+}
+```
+
+5.3. Verify deny rules do not block legitimate development work.
+
+---
+
+## Phase 6: Workflow Integration
+
+**Goal:** Make Claude Code work within the project's existing workflows.
+
+### Steps
+
+6.1. Configure pre-tool-use hooks to align with existing linters:
+   - After writing code, suggest running the project's lint command
+   - After modifying tests, suggest running the project's test command
+
+6.2. Align git behavior with team conventions:
+   - Detect commit message format from history (conventional commits, etc.)
+   - Document branch naming conventions
+   - Note any PR template or review requirements
+
+6.3. Set up notification hooks for critical operations:
+   - Alert when modifying shared configuration files
+   - Alert when adding new dependencies
+
+---
+
+## Output Format
+
+```yaml
+brownfield_setup_result:
+  project_analysis:
+    language: "TypeScript"
+    framework: "Next.js 14"
+    patterns_detected: 12
+    tooling_detected: ["ESLint", "Prettier", "Jest", "GitHub Actions"]
+  files_created:
+    - "CLAUDE.md"
+    - ".claude/settings.json"
+    - ".claude/rules/code-style.md"
+    - ".claude/rules/architecture.md"
+    - ".claude/rules/anti-patterns.md"
+  critical_paths_protected: 5
+  deny_rules_configured: 5
+  existing_workflows_integrated: true
+  disruption_risk: "none"
+  overall_status: "PASS"
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Project has no existing source code | HALT -- use integrate-project for greenfield |
+| CLAUDE.md exists and is manually maintained | WARN -- ask before overwriting |
+| Cannot detect any coding patterns (empty repo) | HALT -- nothing to learn from |
+| Critical paths list is empty and project is large | WARN -- strongly recommend identifying critical paths |
+| Existing .claude/settings.json has deny rules | MERGE -- add to existing rules, do not replace |

package/squads/claude-code-mastery/tasks/ci-cd-setup.md

@@ -0,0 +1,335 @@
+# Task: Claude Code CI/CD Pipeline Setup
+
+**Task ID:** ci-cd-setup
+**Version:** 1.0
+**Purpose:** Configure Claude Code for headless execution in CI/CD pipelines (PR review, code generation, testing)
+**Orchestrator:** @project-integrator (Conduit)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Pipeline runs successfully in headless mode, safety limits configured, costs controlled
+
+---
+
+## Overview
+
+This task sets up Claude Code to run in CI/CD pipelines using headless mode (`claude -p`). It covers GitHub Actions integration, API key management, output format configuration, and safety limits to prevent runaway costs.
+
+```
+INPUT (ci_platform + integration_pattern + budget)
+    |
+[PHASE 1: INTEGRATION PATTERN SELECTION]
+    -> Choose what Claude does in CI (review, generate, test)
+    -> Define trigger events (PR open, push, comment)
+    -> Set scope and limitations
+    |
+[PHASE 2: HEADLESS MODE CONFIGURATION]
+    -> Configure claude -p for non-interactive use
+    -> Set --output-format for machine-readable output
+    -> Configure --max-turns for cost control
+    |
+[PHASE 3: GITHUB ACTIONS WORKFLOW]
+    -> Create .github/workflows/claude-*.yml
+    -> Configure trigger events
+    -> Set up job steps
+    |
+[PHASE 4: API KEY AND ENVIRONMENT]
+    -> Set up ANTHROPIC_API_KEY as secret
+    -> Configure environment variables
+    -> Set up caching for Claude Code CLI
+    |
+[PHASE 5: OUTPUT FORMAT AND PARSING]
+    -> Configure --output-format stream-json
+    -> Parse output for PR comments
+    -> Handle error output
+    |
+[PHASE 6: SAFETY LIMITS]
+    -> Set --max-turns to cap execution
+    -> Configure cost budget per run
+    -> Set up alerting for anomalies
+    |
+OUTPUT: CI/CD workflow files + secrets docs + safety config
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| ci_platform | enum | User | yes | github-actions / gitlab-ci / other |
+| integration_pattern | enum | User | yes | pr-review / code-gen / testing / custom |
+| max_cost_per_run | string | User | no | Budget cap (default: $1.00) |
+| trigger_events | array | User | no | When to run (default: pull_request) |
+| claude_version | string | User | no | Pin to specific version or "latest" |
+
+---
+
+## Preconditions
+
+1. GitHub repository with Actions enabled (or equivalent CI platform)
+2. Anthropic API key available
+3. Repository has existing CI/CD (recommended, not required)
+4. Understanding of which tasks Claude should automate
+
+---
+
+## Phase 1: Integration Pattern Selection
+
+**Goal:** Choose the right CI integration pattern.
+
+### Available Patterns
+
+| Pattern | Trigger | What Claude Does | Typical Cost |
+|---------|---------|-----------------|--------------|
+| **PR Review** | `pull_request` | Reviews code changes, posts comments | $0.10-0.50/PR |
+| **Code Generation** | `workflow_dispatch` or comment | Generates code from spec/issue | $0.50-2.00/run |
+| **Test Generation** | `pull_request` | Generates tests for new code | $0.20-1.00/PR |
+| **Documentation** | `push` to main | Updates docs for changed code | $0.10-0.30/push |
+| **Issue Triage** | `issues.opened` | Categorizes and labels issues | $0.05-0.10/issue |
+
+### Steps
+
+1.1. Select one or more patterns based on team needs.
+1.2. Define the specific prompt for each pattern.
+1.3. Set expected output format (comment, file, label).
+
+---
+
+## Phase 2: Headless Mode Configuration
+
+**Goal:** Configure Claude Code for non-interactive execution.
+
+### Headless Mode Basics
+
+```bash
+# Basic headless execution
+claude -p "Review the changes in this PR for bugs and security issues"
+
+# With output format
+claude -p "..." --output-format stream-json
+
+# With turn limit
+claude -p "..." --max-turns 10
+
+# With specific model
+claude -p "..." --model sonnet
+
+# With system prompt from file
+claude -p "..." --system-prompt "$(cat .claude/ci-system-prompt.md)"
+```
+
+### Key Flags
+
+| Flag | Purpose | Recommended |
+|------|---------|-------------|
+| `-p` | Non-interactive mode (read from argument) | Always use in CI |
+| `--output-format stream-json` | Machine-parseable JSON output | For automated processing |
+| `--output-format text` | Plain text output | For simple logging |
+| `--max-turns` | Limit tool calls | Always set (default: 10) |
+| `--model` | Select model | sonnet for cost, opus for quality |
+| `--no-telemetry` | Disable telemetry | Recommended for CI |
+
+### Steps
+
+2.1. Compose the headless command for each integration pattern.
+2.2. Create a system prompt file for CI context (`.claude/ci-system-prompt.md`).
+2.3. Test the command locally before adding to CI.
+
+---
+
+## Phase 3: GitHub Actions Workflow
+
+**Goal:** Create the CI workflow file.
+
+### GitHub Actions Template
+
+```yaml
+name: Claude Code Review
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  claude-review:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code@latest
+
+      - name: Run Claude Review
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          DIFF=$(git diff origin/main...HEAD)
+          claude -p "Review these changes for bugs, security issues, and code quality. Be concise. Changes: $DIFF" \
+            --output-format text \
+            --max-turns 10 \
+            --model sonnet \
+            > review-output.txt
+
+      - name: Post Review Comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const review = fs.readFileSync('review-output.txt', 'utf8');
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: `## Claude Code Review\n\n${review}`
+            });
+```
+
+### Steps
+
+3.1. Create `.github/workflows/claude-review.yml` (or equivalent).
+3.2. Configure trigger events.
+3.3. Set appropriate `timeout-minutes` (10 for reviews, 30 for generation).
+3.4. Add `permissions` block for required GitHub token scopes.
+
+---
+
+## Phase 4: API Key and Environment
+
+**Goal:** Securely configure API access.
+
+### Steps
+
+4.1. Add `ANTHROPIC_API_KEY` as a repository secret:
+   - Go to Settings > Secrets and variables > Actions
+   - Add `ANTHROPIC_API_KEY` with the API key value
+
+4.2. Configure additional environment variables if needed:
+
+```yaml
+env:
+  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  CLAUDE_MODEL: "sonnet"
+  CLAUDE_MAX_TURNS: "10"
+```
+
+4.3. Security considerations:
+   - NEVER log the API key
+   - NEVER pass the key as a command argument (use env var)
+   - Use repository secrets, not environment variables in workflow files
+   - Consider using OIDC for keyless authentication if available
+
+---
+
+## Phase 5: Output Format and Parsing
+
+**Goal:** Configure output for machine consumption.
+
+### Stream JSON Format
+
+When using `--output-format stream-json`, output is newline-delimited JSON:
+
+```json
+{"type": "assistant", "content": "Here is my analysis..."}
+{"type": "tool_use", "tool": "Read", "input": {"file_path": "..."}}
+{"type": "tool_result", "content": "..."}
+{"type": "assistant", "content": "Based on reading the file..."}
+```
+
+### Steps
+
+5.1. Choose output format based on integration pattern:
+   - PR review -> `text` (for posting as comment)
+   - Code generation -> `stream-json` (for parsing file changes)
+   - Testing -> `text` (for test result summary)
+
+5.2. Create a parsing script if using `stream-json`:
+
+```bash
+# Extract final assistant message
+claude -p "..." --output-format stream-json | \
+  jq -s '[.[] | select(.type == "assistant")] | last | .content'
+```
+
+5.3. Handle error cases:
+   - Empty output -> Claude could not process
+   - Timeout -> increase timeout or reduce scope
+   - Rate limit -> add retry logic with backoff
+
+---
+
+## Phase 6: Safety Limits
+
+**Goal:** Prevent runaway costs and unintended behavior.
+
+### Safety Configuration
+
+| Limit | Value | Purpose |
+|-------|-------|---------|
+| `--max-turns` | 10 (review), 25 (generation) | Cap tool call iterations |
+| `timeout-minutes` | 10 (review), 30 (generation) | GitHub Actions job timeout |
+| Max diff size | 5000 lines | Skip very large PRs |
+| Cost per run | $1.00 default | Alert if exceeded |
+| Runs per day | 50 | Prevent abuse on high-activity repos |
+
+### Steps
+
+6.1. Set `--max-turns` for every `claude -p` invocation.
+6.2. Add a diff size check before running Claude:
+
+```bash
+DIFF_LINES=$(git diff origin/main...HEAD | wc -l)
+if [ "$DIFF_LINES" -gt 5000 ]; then
+  echo "PR too large for automated review ($DIFF_LINES lines)"
+  exit 0
+fi
+```
+
+6.3. Configure job concurrency to prevent parallel runs:
+
+```yaml
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+```
+
+6.4. Set up cost monitoring (check Anthropic usage dashboard).
+
+---
+
+## Output Format
+
+```yaml
+ci_cd_setup_result:
+  platform: "github-actions"
+  integration_pattern: "pr-review"
+  files_created:
+    - ".github/workflows/claude-review.yml"
+    - ".claude/ci-system-prompt.md"
+  secrets_required:
+    - "ANTHROPIC_API_KEY"
+  safety_limits:
+    max_turns: 10
+    timeout_minutes: 10
+    max_diff_lines: 5000
+  estimated_cost_per_run: "$0.10-0.50"
+  tested: true
+  overall_status: "PASS"
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| No CI platform access (cannot create workflows) | HALT -- need admin access |
+| API key not available | HALT -- cannot configure without key |
+| Repository is public and key would be exposed | HALT -- ensure secrets are properly configured |
+| Cost budget is zero | HALT -- headless mode incurs API costs |
+| CI platform not supported (no GitHub Actions, no GitLab CI) | HALT -- manual setup required |