sinapse-ai 7.1.0 → 7.3.0

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

@@ -0,0 +1,236 @@
+# Task: Setup Wizard
+
+**Task ID:** CCM-CHIEF-003
+**Version:** 1.0.0
+**Command:** `*setup-wizard`
+**Orchestrator:** Orion (claude-mastery-chief)
+**Purpose:** Interactive wizard to set up Claude Code for a new or existing project, generating all required configuration files tailored to the detected project type.
+
+---
+
+## Overview
+
+```
+  +------------------+     +------------------+     +------------------+
+  | 1. Detect        | --> | 2. Generate      | --> | 3. Configure     |
+  |    Project Type  |     |    CLAUDE.md     |     |    settings.json |
+  +------------------+     +------------------+     +------------------+
+       |                                                    |
+       v                                                    v
+  +------------------+     +------------------+     +------------------+
+  | 4. Create        | --> | 5. Configure     | --> | 6. Set Up        |
+  |    .claude/rules |     |    Hooks         |     |    MCP Servers   |
+  +------------------+     +------------------+     +------------------+
+       |                                                    |
+       v                                                    v
+  +------------------+     +------------------+
+  | 7. Create        | --> |    COMPLETE      |
+  |    Agents (opt.) |     |    Summary       |
+  +------------------+     +------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Working directory | Yes | Must be a valid directory |
+| mode | string | User parameter | No | `guided` (default, interactive) or `express` (smart defaults) |
+| preset | string | User parameter | No | Project type override (monorepo, fullstack, library, api, cli) |
+
+---
+
+## Preconditions
+
+- Working directory is a project root
+- Write access to the project directory
+- No existing .claude/ directory (or user confirms overwrite)
+
+---
+
+## Execution Phases
+
+### Phase 1: Detect Project Type
+
+Analyze the project to determine its type:
+
+1. Check for project markers:
+   - `package.json` -> Node.js project; check for `workspaces` field (monorepo)
+   - `next.config.*` -> Next.js fullstack
+   - `vite.config.*` -> Vite frontend
+   - `tsconfig.json` -> TypeScript project
+   - `pyproject.toml` / `setup.py` -> Python project
+   - `Cargo.toml` -> Rust project
+   - `go.mod` -> Go project
+   - `.sinapse-ai/` -> SINAPSE-managed project
+2. Detect project structure:
+   - `src/app/` or `app/` -> App Router (Next.js)
+   - `src/pages/` -> Pages Router
+   - `packages/` or `apps/` -> Monorepo
+   - `src/lib/` or `lib/` -> Library
+   - `src/api/` or `server/` -> API backend
+3. Present detection result and ask user to confirm or override
+
+**Project Type Matrix:**
+
+| Type | Markers | Default Permission Mode |
+|------|---------|------------------------|
+| monorepo | workspaces, packages/ | acceptEdits |
+| fullstack | next.config, app/ + api/ | acceptEdits |
+| frontend | vite.config, src/components | acceptEdits |
+| api | server/, express/fastify dep | acceptEdits |
+| library | main/module in package.json | askAlways |
+| cli | bin/ field in package.json | askAlways |
+| python | pyproject.toml, src/ | acceptEdits |
+| sinapse | .sinapse-ai/ directory | acceptEdits |
+
+### Phase 2: Generate CLAUDE.md
+
+1. Create `.claude/CLAUDE.md` (or `./CLAUDE.md` based on user preference)
+2. Include sections based on project type:
+   - **Project overview**: Name, description, tech stack
+   - **Development commands**: Build, test, lint, dev server
+   - **Code standards**: Naming conventions, patterns, file organization
+   - **Testing**: Test framework, coverage requirements, how to run
+   - **Architecture notes**: Key directories and their purpose
+3. Use @imports for large reference documents
+4. Target: under 200 lines
+5. If SINAPSE project: include SINAPSE-specific sections (agent system, workflows)
+
+### Phase 3: Configure settings.json
+
+1. Create `.claude/settings.json` with:
+   - **permissions.deny**: Sensitive files (.env, secrets/, credentials)
+   - **permissions.allow**: Safe development operations based on project type
+   - **permissions.defaultMode**: Based on project type matrix
+2. Add project-specific rules:
+   - Monorepo: allow Read/Edit across all packages
+   - Frontend: allow Bash(npm run dev), Bash(npm run build)
+   - API: deny external network calls by default
+   - Library: stricter permissions (askAlways)
+3. If SINAPSE project: add L1-L4 boundary protection deny rules
+
+### Phase 4: Set Up .claude/rules/
+
+1. Create `.claude/rules/` directory
+2. Generate conditional rules based on project structure:
+   - **api-rules.md**: API conventions (if src/api/ or server/ exists)
+     - `paths: ["src/api/**", "server/**"]`
+   - **test-rules.md**: Testing conventions (if tests/ or __tests__/ exists)
+     - `paths: ["tests/**", "**/*.test.*", "**/*.spec.*"]`
+   - **component-rules.md**: Component patterns (if src/components/ exists)
+     - `paths: ["src/components/**", "**/*.tsx"]`
+   - **database-rules.md**: Migration patterns (if migrations/ or supabase/ exists)
+     - `paths: ["migrations/**", "supabase/**"]`
+3. Create one unconditional rule for project-wide conventions
+
+### Phase 5: Configure Hooks
+
+1. Ask the user about their automation needs:
+   - Pre-commit validation? (lint, format, type check)
+   - Command safety? (block dangerous bash commands)
+   - Session logging? (track tool usage)
+   - Compaction preservation? (save context before auto-compaction)
+2. Generate hook configuration based on answers:
+   ```json
+   {
+     "hooks": {
+       "PreToolUse": [{
+         "matcher": "Bash",
+         "hooks": [{ "type": "command", "command": "...", "timeout": 10 }]
+       }],
+       "PreCompact": [{
+         "hooks": [{ "type": "command", "command": "...", "timeout": 5 }]
+       }]
+     }
+   }
+   ```
+3. For express mode: apply sensible defaults (PreToolUse bash guard + PreCompact)
+
+### Phase 6: Set Up MCP Servers
+
+1. Ask the user which capabilities they need:
+   - Web search (Exa)
+   - Library documentation (Context7)
+   - Browser automation (Playwright)
+   - Database access (Supabase, Postgres)
+   - File system extended access
+2. Generate `.claude/mcp.json` with selected servers
+3. Provide setup instructions for each server (install commands, API keys needed)
+4. For express mode: configure Context7 (most universally useful)
+
+### Phase 7: Create Agents (Optional)
+
+1. Ask if the user needs custom subagents
+2. If yes, create `.claude/agents/` directory with starter agents:
+   - **reviewer.md**: Code review agent with Read-only tools
+   - **planner.md**: Planning agent with limited scope
+3. Each agent gets proper YAML frontmatter:
+   ```yaml
+   ---
+   name: Reviewer
+   description: Code review specialist
+   tools: [Read, Grep, Glob]
+   ---
+   ```
+4. For express mode: skip unless user explicitly requests
+
+---
+
+## Output Format
+
+```markdown
+## Setup Complete
+
+**Project:** {project-name}
+**Type:** {detected-type}
+**Mode:** {guided | express}
+
+### Files Created
+
+| File | Purpose | Lines |
+|------|---------|-------|
+| .claude/CLAUDE.md | Project instructions | {N} |
+| .claude/settings.json | Permissions and config | {N} |
+| .claude/rules/{name}.md | Conditional rule | {N} |
+| ... | ... | ... |
+
+### Configuration Summary
+
+- **Permission mode:** {defaultMode}
+- **Deny rules:** {count} rules protecting sensitive files
+- **Allow rules:** {count} rules for development operations
+- **Hooks:** {count} hooks configured ({event names})
+- **MCP servers:** {count} servers ({names})
+- **Custom agents:** {count} agents ({names})
+
+### Next Steps
+
+1. Review .claude/settings.json and adjust permissions
+2. Customize CLAUDE.md with project-specific instructions
+3. Run `*audit` to verify the setup scores well
+4. {Additional steps based on project type}
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** overwrite existing .claude/ configuration without explicit user confirmation. Always ask first.
+- **NEVER** include real API keys, tokens, or secrets in generated configuration files. Use placeholder values with comments.
+- **NEVER** set `bypassPermissions` as the default mode. Start with `acceptEdits` or `askAlways`.
+- **NEVER** create a CLAUDE.md over 200 lines. Split into @imports and .claude/rules/ if content exceeds the limit.
+- **NEVER** skip the project type detection confirmation step, even in express mode.
+
+---
+
+## Completion Criteria
+
+- [ ] Project type detected and confirmed
+- [ ] CLAUDE.md generated under 200 lines
+- [ ] settings.json created with deny-first permission rules
+- [ ] At least one .claude/rules/ file created with paths: frontmatter
+- [ ] Hooks configured (at minimum in guided mode)
+- [ ] MCP servers section addressed (configured or explicitly skipped)
+- [ ] Setup summary displayed with file list and next steps

package/squads/claude-code-mastery/tasks/worktree-strategy.md

@@ -0,0 +1,320 @@
+# Task: Git Worktree Isolation Strategy
+
+**Task ID:** worktree-strategy
+**Version:** 1.0
+**Purpose:** Plan and configure git worktree isolation for multi-agent development scenarios
+**Orchestrator:** @swarm-orqx (Nexus)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Worktree lifecycle tested end-to-end, cleanup verified
+
+---
+
+## Overview
+
+This task plans git worktree isolation for agent teams where multiple agents modify code simultaneously. Worktrees give each agent its own working directory and branch, eliminating merge conflicts during execution and deferring integration to a controlled merge phase.
+
+```
+INPUT (agents_count + shared_files_risk + merge_strategy)
+    |
+[PHASE 1: ISOLATION ASSESSMENT]
+    -> Evaluate merge conflict risk
+    -> Determine if worktree isolation is needed
+    -> Identify alternative strategies
+    |
+[PHASE 2: BRANCH STRATEGY]
+    -> Define branch naming convention
+    -> Plan base branch selection
+    -> Set up branch protection
+    |
+[PHASE 3: WORKTREE CONFIGURATION]
+    -> Create worktrees for each agent
+    -> Configure agent working directories
+    -> Verify each worktree is functional
+    |
+[PHASE 4: LIFECYCLE MANAGEMENT]
+    -> Define create -> work -> merge -> cleanup flow
+    -> Set up automated cleanup triggers
+    -> Plan stale worktree detection
+    |
+[PHASE 5: MERGE AND CLEANUP]
+    -> Define merge order (dependency-aware)
+    -> Handle merge conflicts
+    -> Remove worktrees after successful merge
+    |
+OUTPUT: Worktree config + branch strategy + lifecycle plan
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| agent_count | number | From team topology | yes | Number of agents needing isolation |
+| base_branch | string | Auto-detect or user | no | Branch to create worktrees from (default: current) |
+| task_id | string | User | yes | Identifier for this parallel work session |
+| shared_files | array | Analysis | no | Files that multiple agents might modify |
+| auto_cleanup | boolean | User | no | Remove worktrees after merge (default: true) |
+
+---
+
+## Preconditions
+
+1. Git repository is initialized and has at least one commit
+2. Current working tree is clean (no uncommitted changes)
+3. `git worktree` command is available (Git 2.5+)
+4. Sufficient disk space for N copies of the working directory
+
+---
+
+## Phase 1: Isolation Assessment
+
+**Goal:** Determine if worktree isolation is actually needed.
+
+### When to Use Worktrees vs Shared Repo
+
+| Scenario | Strategy | Reason |
+|----------|----------|--------|
+| Agents modify different files | **Shared repo** | No conflict risk, simpler setup |
+| Agents modify same files | **Worktree** | Prevents runtime merge conflicts |
+| Sequential pipeline (A then B) | **Shared repo** | No simultaneous writes |
+| Parallel agents with file overlap | **Worktree** | Each agent needs clean state |
+| Single agent with long-running task | **Shared repo** | No need for isolation |
+| CI/CD parallel test execution | **Worktree** | Tests need independent environments |
+
+### Steps
+
+1.1. Analyze agent assignments from the team topology.
+1.2. Build a file-ownership matrix:
+
+```
+         | Agent-A | Agent-B | Agent-C |
+---------|---------|---------|---------|
+file1.ts |   W     |   R     |         |
+file2.ts |         |   W     |   W     |  <-- CONFLICT
+file3.ts |   W     |         |         |
+```
+
+1.3. If any file has multiple W (write) entries, worktree isolation is recommended.
+1.4. If no conflicts, document decision to use shared repo and SKIP remaining phases.
+
+---
+
+## Phase 2: Branch Strategy
+
+**Goal:** Define how branches map to agents and worktrees.
+
+### Branch Naming Convention
+
+```
+{task-id}/{agent-name}
+
+Examples:
+  feature-auth/code-reviewer
+  feature-auth/test-writer
+  feature-auth/docs-updater
+```
+
+### Steps
+
+2.1. Define the base branch (where worktrees branch from):
+   - Use current branch for story work
+   - Use `main` for independent feature work
+
+2.2. Create a branch plan:
+
+```yaml
+branches:
+  base: "feature/auth-system"
+  worktree_branches:
+    - name: "feature/auth-system/api-agent"
+      agent: "api-agent"
+      files_owned: ["src/api/**"]
+    - name: "feature/auth-system/test-agent"
+      agent: "test-agent"
+      files_owned: ["tests/**"]
+    - name: "feature/auth-system/docs-agent"
+      agent: "docs-agent"
+      files_owned: ["docs/**"]
+```
+
+2.3. Verify no branch names conflict with existing branches.
+
+---
+
+## Phase 3: Worktree Configuration
+
+**Goal:** Create and configure worktrees for each agent.
+
+### Worktree Location
+
+Worktrees are created as sibling directories to the main repo:
+
+```
+project/                    <-- main working tree
+project-wt-api-agent/      <-- worktree for api-agent
+project-wt-test-agent/     <-- worktree for test-agent
+project-wt-docs-agent/     <-- worktree for docs-agent
+```
+
+### Steps
+
+3.1. For each agent, create a worktree:
+
+```bash
+# Create branch and worktree together
+git worktree add ../project-wt-{agent-name} -b {branch-name} {base-branch}
+```
+
+3.2. Verify each worktree is functional:
+
+```bash
+git worktree list
+# Should show main + N worktrees
+```
+
+3.3. Configure each agent to use its worktree directory as working directory.
+3.4. Install dependencies in each worktree if needed (e.g., `npm install`).
+
+---
+
+## Phase 4: Lifecycle Management
+
+**Goal:** Define the full create-work-merge-cleanup lifecycle.
+
+### Lifecycle Flow
+
+```
+CREATE                 WORK                    MERGE                CLEANUP
+  |                     |                       |                    |
+  Create worktree  ->  Agent works         ->  Merge branch    ->  Remove worktree
+  Create branch        in isolation             to base             Delete branch
+  Install deps         Commits to branch        Resolve conflicts   Verify clean
+  |                     |                       |                    |
+  [Automated]          [Agent-driven]          [Orchestrated]      [Automated]
+```
+
+### Steps
+
+4.1. Document the lifecycle for this specific task:
+
+```yaml
+lifecycle:
+  create:
+    trigger: "Task start"
+    steps: ["create worktree", "create branch", "install deps"]
+    estimated_time: "1-3 min"
+  work:
+    trigger: "Agent activation"
+    duration: "Variable"
+    monitoring: "Progress file in shared location"
+  merge:
+    trigger: "All agents complete"
+    order: ["api-agent", "test-agent", "docs-agent"]
+    conflict_resolution: "manual"
+  cleanup:
+    trigger: "Merge complete + verified"
+    steps: ["remove worktree", "delete branch"]
+    auto: true
+```
+
+4.2. Define stale worktree detection:
+   - Worktree with no commits in 24 hours = potentially stale
+   - Worktree from deleted/merged branch = definitely stale
+4.3. Set up cleanup command:
+
+```bash
+# Remove a specific worktree
+git worktree remove ../project-wt-{agent-name}
+
+# Prune stale worktree references
+git worktree prune
+```
+
+---
+
+## Phase 5: Merge and Cleanup
+
+**Goal:** Safely merge all agent work back to the base branch.
+
+### Merge Order
+
+5.1. Merge in dependency order (agents whose work is depended on merge first):
+
+```
+1. api-agent    (no dependencies on other agents)
+2. test-agent   (may import from api-agent's code)
+3. docs-agent   (documents what api-agent + test-agent built)
+```
+
+5.2. For each merge:
+
+```bash
+# Switch to base branch
+git checkout {base-branch}
+
+# Merge agent branch
+git merge {agent-branch} --no-ff -m "merge: {agent-name} work for {task-id}"
+
+# If conflict:
+#   1. Identify conflicting files
+#   2. Resolve manually or with orchestrator guidance
+#   3. Commit resolution
+```
+
+5.3. After all merges complete:
+   - Run full test suite on merged result
+   - If tests fail, identify which merge introduced the failure
+   - Fix or revert as needed
+
+5.4. Cleanup:
+
+```bash
+# Remove all worktrees for this task
+git worktree remove ../project-wt-api-agent
+git worktree remove ../project-wt-test-agent
+git worktree remove ../project-wt-docs-agent
+
+# Delete merged branches
+git branch -d feature/auth-system/api-agent
+git branch -d feature/auth-system/test-agent
+git branch -d feature/auth-system/docs-agent
+
+# Prune any lingering references
+git worktree prune
+```
+
+---
+
+## Output Format
+
+```yaml
+worktree_strategy_result:
+  isolation_needed: true
+  reason: "2 agents modify overlapping files in src/"
+  worktrees:
+    - agent: "api-agent"
+      path: "../project-wt-api-agent"
+      branch: "feature/auth-system/api-agent"
+      status: "created"
+    - agent: "test-agent"
+      path: "../project-wt-test-agent"
+      branch: "feature/auth-system/test-agent"
+      status: "created"
+  merge_order: ["api-agent", "test-agent"]
+  auto_cleanup: true
+  lifecycle_documented: true
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Git repository has no commits | HALT -- initialize repo first |
+| Uncommitted changes in working tree | HALT -- commit or stash before creating worktrees |
+| Disk space insufficient for N worktrees | HALT -- estimate ~size of repo per worktree |
+| Git version < 2.5 | HALT -- upgrade git for worktree support |
+| No file conflicts detected between agents | SKIP -- use shared repo instead (simpler) |
+| Worktree creation fails | HALT -- check git lock files and existing worktrees |

package/squads/claude-code-mastery/templates/claude-md-fullstack.md

@@ -0,0 +1,147 @@
+# CLAUDE.md — Fullstack Project (Next.js + React)
+
+## Project Overview
+
+- **Name:** [PROJECT_NAME]
+- **Description:** [Brief description of the application]
+- **Type:** Fullstack web application
+- **Framework:** Next.js (App Router)
+- **Status:** [Development / Staging / Production]
+
+## Tech Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Framework | Next.js | 15.x |
+| UI Library | React | 19.x |
+| Language | TypeScript | 5.x |
+| Styling | Tailwind CSS | 4.x |
+| UI Components | shadcn/ui | latest |
+| State (client) | Zustand | 5.x |
+| Data Fetching | TanStack Query | 5.x |
+| Database | PostgreSQL | via Supabase |
+| Auth | Supabase Auth | — |
+| Validation | Zod | 3.x |
+| Testing | Jest + React Testing Library | — |
+| Linting | ESLint + Prettier | — |
+
+## Directory Structure
+
+```
+src/
+  app/                    # Next.js App Router pages
+    (auth)/               # Auth route group (login, register)
+    (dashboard)/          # Dashboard route group
+    api/                  # API route handlers
+    layout.tsx            # Root layout
+    page.tsx              # Landing page
+  components/
+    ui/                   # shadcn/ui base components
+    shared/               # Shared composite components
+    features/             # Feature-specific components
+  lib/
+    supabase/             # Supabase client configuration
+    utils.ts              # Utility functions
+    constants.ts          # Application constants
+  hooks/                  # Custom React hooks
+  stores/                 # Zustand stores
+  types/                  # TypeScript type definitions
+  styles/                 # Global styles, Tailwind config
+```
+
+## Code Standards
+
+### Components
+- Use function components with TypeScript interfaces for props
+- Prefer named exports: `export function Button() {}` not `export default`
+- Co-locate component tests: `Button.tsx` + `Button.test.tsx`
+- Separate server components (default) from client components (`'use client'`)
+- Keep components under 200 lines; extract logic into hooks
+
+### Naming Conventions
+- Components: PascalCase (`UserProfile.tsx`)
+- Hooks: camelCase with `use` prefix (`useAuth.ts`)
+- Utilities: camelCase (`formatDate.ts`)
+- Types: PascalCase with descriptive suffixes (`UserProfileProps`, `AuthState`)
+- API routes: lowercase with hyphens (`/api/user-profile/route.ts`)
+- Constants: SCREAMING_SNAKE_CASE (`MAX_RETRY_COUNT`)
+
+### Server vs Client Components
+- **Server Components** (default): Data fetching, database access, sensitive logic
+- **Client Components** (`'use client'`): Interactivity, browser APIs, state, effects
+- Never import server-only modules in client components
+- Pass serializable props from server to client components
+
+### API Patterns
+- API routes in `src/app/api/` using Route Handlers
+- Validate all inputs with Zod schemas
+- Return consistent response shapes: `{ data, error, meta }`
+- Use proper HTTP status codes (200, 201, 400, 401, 404, 500)
+- Handle errors with try/catch, never expose internal errors
+
+### State Management
+- **Server state:** TanStack Query for all API data (caching, revalidation)
+- **Client state:** Zustand for UI state (modals, sidebars, preferences)
+- **Form state:** React Hook Form + Zod validation
+- Never duplicate server state in client stores
+
+## Testing Requirements
+
+- Run all tests: `npm test`
+- Run with coverage: `npm test -- --coverage`
+- Minimum coverage: 80% for business logic, 60% for components
+- Test files: `*.test.ts` or `*.test.tsx` co-located with source
+- Use `@testing-library/react` for component tests
+- Mock Supabase client in tests, never hit real database
+
+## Git Conventions
+
+- **Commits:** Conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `test:`, `refactor:`)
+- **Branches:** `feat/description`, `fix/description`, `chore/description`
+- **PR titles:** Same as conventional commits
+- Reference issue/story: `feat: add user profile page [STORY-1.2]`
+
+## Common Commands
+
+```bash
+npm run dev          # Start development server (localhost:3000)
+npm run build        # Production build
+npm run start        # Start production server
+npm test             # Run Jest tests
+npm run lint         # ESLint check
+npm run lint:fix     # ESLint auto-fix
+npm run typecheck    # TypeScript type checking
+npm run format       # Prettier formatting
+```
+
+## Environment Variables
+
+- `.env.local` for local development (gitignored)
+- `.env.example` as template (committed)
+- Required: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+- Server-only: `SUPABASE_SERVICE_ROLE_KEY` (never prefix with `NEXT_PUBLIC_`)
+
+## Error Handling
+
+```typescript
+// API route pattern
+export async function GET(request: Request) {
+  try {
+    const data = await fetchData();
+    return NextResponse.json({ data });
+  } catch (error) {
+    console.error('GET /api/resource failed:', error);
+    return NextResponse.json(
+      { error: 'Failed to fetch resource' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+## Important Notes
+
+- Always check `npm run typecheck` before committing
+- Never store secrets in client-side code or `NEXT_PUBLIC_` variables
+- Use `loading.tsx` and `error.tsx` for route-level loading/error states
+- Prefer Server Actions for mutations over API routes when possible