sinapse-ai 7.1.0 → 7.3.0

package/squads/claude-code-mastery/tasks/parallel-decomposition.md

@@ -0,0 +1,293 @@
+# Task: Parallel Task Decomposition for Agent Execution
+
+**Task ID:** parallel-decomposition
+**Version:** 1.0
+**Purpose:** Decompose a complex task into subtasks for parallel multi-agent execution
+**Orchestrator:** @swarm-orqx (Nexus)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Dependency graph validated, no circular dependencies, merge strategy tested
+
+---
+
+## Overview
+
+This task analyzes a workload, identifies independent subtasks, designs a parallel execution plan, and configures agents for simultaneous execution. The key insight: **maximum parallelism comes from minimizing dependencies, not maximizing agents**.
+
+```
+INPUT (task_description + constraints)
+    |
+[PHASE 1: TASK ANALYSIS]
+    -> Break task into atomic subtasks
+    -> Classify each subtask's complexity
+    -> Estimate execution time per subtask
+    |
+[PHASE 2: DEPENDENCY MAPPING]
+    -> Identify data dependencies between subtasks
+    -> Identify resource conflicts (same files, same APIs)
+    -> Build dependency graph
+    |
+[PHASE 3: EXECUTION PLAN]
+    -> Group independent subtasks into waves
+    -> Assign agents to each wave
+    -> Configure foreground vs background execution
+    |
+[PHASE 4: AGENT CONFIGURATION]
+    -> Create or select agent definitions
+    -> Set model tiers per subtask complexity
+    -> Configure tool permissions
+    |
+[PHASE 5: MERGE STRATEGY]
+    -> Define how agent outputs combine
+    -> Handle conflicting changes
+    -> Plan integration verification
+    |
+[PHASE 6: MONITORING]
+    -> Set up progress tracking
+    -> Define timeout thresholds
+    -> Plan failure recovery
+    |
+OUTPUT: Execution plan + dependency graph + agent configs + merge strategy
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| task_description | string | User | yes | Full description of the work to parallelize |
+| max_parallel_agents | number | User or default | no | Maximum simultaneous agents (default: 4) |
+| isolation_mode | enum | User | no | shared / worktree / branch (default: shared) |
+| time_constraint | string | User | no | Target completion time |
+| cost_constraint | enum | User | no | low / medium / high (affects model selection) |
+
+---
+
+## Preconditions
+
+1. Task is large enough to benefit from parallelization (2+ independent subtasks)
+2. Claude Code is operational with Agent tool available
+3. Sufficient API rate limits for parallel agent calls
+4. Git repository is clean (no uncommitted changes) if using worktree isolation
+
+---
+
+## Phase 1: Task Analysis
+
+**Goal:** Break the task into the smallest independent units of work.
+
+### Steps
+
+1.1. Read the full task description.
+1.2. Identify atomic subtasks -- each should be:
+   - Completable by a single agent
+   - Testable independently
+   - Producing a clear output artifact
+1.3. Classify each subtask:
+
+| Complexity | Lines of Change | Model | Estimated Time |
+|------------|----------------|-------|----------------|
+| Trivial | < 20 lines | haiku | 1-2 min |
+| Simple | 20-100 lines | sonnet | 3-5 min |
+| Standard | 100-500 lines | sonnet | 5-15 min |
+| Complex | 500+ lines | opus | 15-30 min |
+
+1.4. Create a subtask inventory table:
+
+```markdown
+| ID | Subtask | Complexity | Est. Time | Dependencies |
+|----|---------|-----------|-----------|--------------|
+| S1 | ...     | simple    | 3 min     | none         |
+| S2 | ...     | standard  | 10 min    | S1           |
+```
+
+---
+
+## Phase 2: Dependency Mapping
+
+**Goal:** Build a dependency graph to identify parallelization opportunities.
+
+### Dependency Types
+
+| Type | Description | Impact |
+|------|-------------|--------|
+| **Data** | S2 needs output from S1 | Must sequence |
+| **Resource** | S1 and S3 modify same file | Must sequence or isolate |
+| **Semantic** | S2 should know what S1 decided | Can use shared context file |
+| **None** | S1 and S4 are fully independent | Can parallelize |
+
+### Steps
+
+2.1. For each subtask pair, determine dependency type.
+2.2. Build a dependency graph:
+
+```
+Dependency Graph Template:
+
+S1 -----> S3 -----> S5
+  \                 ^
+   \               /
+S2 -----> S4 -----
+
+Legend: Arrow = "must complete before"
+Parallel: {S1, S2} can run together
+Sequential: S3 waits for S1, S4 waits for S2
+Join: S5 waits for S3 and S4
+```
+
+2.3. Detect circular dependencies (VETO if found).
+2.4. Calculate critical path (longest sequential chain).
+
+---
+
+## Phase 3: Execution Plan
+
+**Goal:** Group subtasks into parallel execution waves.
+
+### Parallelization Patterns
+
+| Pattern | Description | Use When |
+|---------|-------------|----------|
+| **Fan-Out/Fan-In** | Dispatch N agents, collect all results | Independent subtasks with shared merge |
+| **Pipeline** | Chain agents A -> B -> C | Sequential transformation |
+| **Scatter-Gather** | Dispatch same task to N agents, pick best | Need diverse approaches to same problem |
+| **Wave** | Groups of parallel tasks with sync points | Mixed dependencies |
+
+### Wave Planning
+
+3.1. Assign subtasks to waves based on dependency graph:
+
+```
+Wave 1: [S1, S2]     -- no dependencies, run parallel
+Wave 2: [S3, S4]     -- depend on Wave 1, run parallel
+Wave 3: [S5]         -- depends on Wave 2
+```
+
+3.2. For each wave, determine execution mode:
+
+| Mode | Mechanism | When to Use |
+|------|-----------|-------------|
+| **Background** | Agent tool with background flag | Fire-and-forget subtasks |
+| **Foreground** | Sequential Agent tool calls | Need result before next step |
+| **Parallel foreground** | Multiple Agent calls in same message | Independent subtasks, need all results |
+
+3.3. Document the execution timeline:
+
+```
+Time ->
+  [==S1==]  [====S3====]  [==S5==]
+  [===S2===]  [==S4==]
+```
+
+---
+
+## Phase 4: Agent Configuration
+
+**Goal:** Create or assign agents for each subtask.
+
+### Steps
+
+4.1. For each subtask, decide:
+   - Use existing agent definition? (search `.claude/agents/`)
+   - Create new agent? (use create-agent-definition task)
+   - Use generic Agent tool with inline prompt?
+
+4.2. Configure model per subtask based on complexity from Phase 1.
+4.3. Set tool permissions -- restrict to minimum needed:
+   - Read-only subtasks: Explore-type agent
+   - Code modification: General-purpose with Write/Edit
+   - Research: Explore-type with Bash for web tools
+
+4.4. Set `max_turns` per agent based on complexity:
+   - Trivial: 5 turns
+   - Simple: 10 turns
+   - Standard: 20 turns
+   - Complex: 40 turns
+
+---
+
+## Phase 5: Merge Strategy
+
+**Goal:** Define how parallel agent outputs combine into a final result.
+
+### Merge Strategies
+
+| Strategy | Description | Conflict Risk |
+|----------|-------------|--------------|
+| **File ownership** | Each agent owns specific files | None |
+| **Directory ownership** | Each agent owns a directory | None |
+| **Git merge** | Each agent on a branch, merge at end | Medium |
+| **Manual review** | Human reviews and merges | Low (but slow) |
+| **Automated merge** | Script merges outputs by convention | Low |
+
+### Steps
+
+5.1. Assign file/directory ownership to each agent.
+5.2. Define the merge process:
+   - Collect outputs from all agents
+   - Verify no conflicts (same file modified by 2+ agents)
+   - If conflicts exist, apply resolution strategy
+   - Run integration tests on merged result
+5.3. If using worktree isolation, plan the branch merge sequence.
+
+---
+
+## Phase 6: Monitoring
+
+**Goal:** Track progress and handle failures.
+
+### Steps
+
+6.1. Define progress checkpoints:
+   - Each agent writes status to a shared progress file
+   - Wave completion triggers next wave
+6.2. Set timeout thresholds per subtask (2x estimated time).
+6.3. Define failure handling:
+   - Agent timeout: Kill and report partial results
+   - Agent error: Retry once with same config
+   - Repeated failure: Escalate to human
+6.4. Plan rollback if merge fails:
+   - Revert to pre-execution state
+   - Report which subtasks succeeded vs failed
+
+---
+
+## Output Format
+
+```yaml
+parallel_decomposition_result:
+  total_subtasks: 5
+  total_waves: 3
+  estimated_sequential_time: "35 min"
+  estimated_parallel_time: "15 min"
+  speedup: "2.3x"
+  critical_path: ["S1", "S3", "S5"]
+  waves:
+    - wave: 1
+      subtasks: ["S1", "S2"]
+      mode: "parallel-foreground"
+    - wave: 2
+      subtasks: ["S3", "S4"]
+      mode: "parallel-foreground"
+    - wave: 3
+      subtasks: ["S5"]
+      mode: "foreground"
+  merge_strategy: "file-ownership"
+  agents_created: [...]
+  dependency_graph: |
+    S1 -> S3 -> S5
+    S2 -> S4 -> S5
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Circular dependency detected in graph | HALT -- restructure subtasks to break cycle |
+| All subtasks are sequentially dependent | HALT -- no parallelization benefit, use single agent |
+| Subtask count exceeds 10 | HALT -- group into higher-level units first |
+| Multiple agents must write to same file | HALT -- redesign with file ownership or worktree |
+| Critical path time exceeds time constraint | WARN -- consider decomposing critical path subtasks further |
+| Estimated cost exceeds budget | HALT -- downgrade models or reduce parallelism |

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

@@ -0,0 +1,266 @@
+# Task: Design Permission Strategy
+
+**Task ID:** CCM-CONFIG-005
+**Version:** 1.0.0
+**Command:** `*permission-strategy`
+**Orchestrator:** Sigil (config-engineer)
+**Purpose:** Design a comprehensive permission strategy for a project by assessing security needs, selecting the appropriate permission mode, and engineering precise allow/ask/deny rules using Claude Code's `Tool(specifier)` syntax.
+
+---
+
+## Overview
+
+```
+  +------------------+     +------------------+     +------------------+
+  | 1. Assess        | --> | 2. Choose        | --> | 3. Configure     |
+  |    Security      |     |    Permission    |     |    Allow Rules   |
+  |    Needs         |     |    Mode          |     |                  |
+  +------------------+     +------------------+     +------------------+
+       |                                                    |
+       v                                                    v
+  +------------------+     +------------------+     +------------------+
+  | 4. Configure     | --> | 5. Set MCP       | --> |    STRATEGY      |
+  |    Deny Rules    |     |    Tool          |     |    DOCUMENT      |
+  +------------------+     |    Permissions   |     +------------------+
+                            +------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Working directory | Yes | Valid project directory |
+| team_size | string | User parameter | No | `solo`, `small` (2-5), `team` (6+), `enterprise` |
+| sensitivity | string | User parameter | No | `low`, `standard` (default), `high`, `regulated` |
+
+---
+
+## Preconditions
+
+- Understanding of the project's technology stack
+- Knowledge of team composition and access patterns
+- Awareness of any compliance requirements (SOC2, HIPAA, etc.)
+
+---
+
+## Execution Phases
+
+### Phase 1: Assess Project Security Needs
+
+1. Determine the sensitivity profile:
+
+| Factor | Weight | Assessment |
+|--------|--------|------------|
+| Handles PII/PHI data | HIGH | Check for user data, health records |
+| Has production credentials | HIGH | .env files, secret managers |
+| External API integrations | MEDIUM | Third-party services, webhooks |
+| Financial transactions | HIGH | Payment processing, billing |
+| Open source project | LOW | Public code, no secrets |
+| Internal tool | MEDIUM | Company data, internal APIs |
+
+2. Scan for sensitive file patterns:
+   - `.env`, `.env.*` -- environment variables
+   - `*.pem`, `*.key`, `*.p12` -- certificates and keys
+   - `secrets/`, `credentials/`, `private/` -- secret directories
+   - `*.tfvars`, `*.tfstate` -- Terraform state with secrets
+   - `docker-compose.*.yml` -- may contain credentials
+3. Identify safe operation patterns:
+   - Read-only operations (git diff, git log, cat)
+   - Build/test operations (npm run, pytest)
+   - Development servers (npm run dev, next dev)
+
+### Phase 2: Choose Permission Mode
+
+Select the base mode based on assessment:
+
+| Mode | Use When | Friction Level | Security Level |
+|------|----------|----------------|----------------|
+| askAlways | Regulated environments, onboarding, high sensitivity | High | Maximum |
+| acceptEdits | Standard development, trusted codebase, medium sensitivity | Medium | Balanced |
+| autoApprove | Solo developer, low sensitivity, personal projects | Low | Minimum |
+| plan | Complex workflows requiring upfront approval (managed only) | Medium | High |
+
+**Decision tree:**
+
+```
+Is this regulated (SOC2, HIPAA)?
+  YES -> askAlways + strict deny rules
+  NO  -> Is it a team project?
+    YES -> acceptEdits + comprehensive deny/allow
+    NO  -> Is it high sensitivity?
+      YES -> acceptEdits + strict deny rules
+      NO  -> autoApprove + basic deny rules (still deny secrets)
+```
+
+Present recommendation with rationale. Allow user override.
+
+### Phase 3: Configure Allow Rules
+
+Build the allow list using `Tool(specifier)` syntax:
+
+**Evaluation order reminder:** deny -> ask -> allow (first match wins).
+
+**Common allow patterns by tool:**
+
+| Tool | Pattern | Purpose |
+|------|---------|---------|
+| `Bash(npm run *)` | Allow all npm scripts | Development workflow |
+| `Bash(npx *)` | Allow npx execution | Tool execution |
+| `Bash(git status)` | Git status check | Version control |
+| `Bash(git diff *)` | Git diff viewing | Code review |
+| `Bash(git log *)` | Git history | Version control |
+| `Bash(git add *)` | Git staging | Version control |
+| `Bash(git commit *)` | Git commits | Version control |
+| `Bash(node *)` | Node.js execution | Development |
+| `Bash(python *)` | Python execution | Development |
+| `Bash(pytest *)` | Python testing | Testing |
+| `Read(src/**)` | Read source code | Development |
+| `Read(docs/**)` | Read documentation | Reference |
+| `Read(tests/**)` | Read test files | Testing |
+| `Edit(src/**)` | Edit source code | Development |
+| `Edit(tests/**)` | Edit test files | Testing |
+| `WebFetch(domain:*.npmjs.org)` | NPM registry | Package info |
+| `WebFetch(domain:api.github.com)` | GitHub API | Repository info |
+| `MCP(context7)` | Library docs | Documentation |
+| `Agent(Explore)` | Exploration subagent | Analysis |
+
+Customize based on detected project needs.
+
+### Phase 4: Configure Deny Rules
+
+Build the deny list (evaluated first, highest priority):
+
+**Mandatory deny rules (always include):**
+
+```json
+{
+  "deny": [
+    "Read(./.env)",
+    "Read(./.env.*)",
+    "Read(./.env.local)",
+    "Read(./secrets/**)",
+    "Read(./**/*.pem)",
+    "Read(./**/*.key)",
+    "Read(./**/*.p12)",
+    "Bash(rm -rf /)",
+    "Bash(rm -rf ~)",
+    "Bash(curl * | bash)",
+    "Bash(wget * | bash)",
+    "Bash(> /dev/sda)"
+  ]
+}
+```
+
+**Project-specific deny rules:**
+
+| Project Type | Additional Deny Rules |
+|-------------|----------------------|
+| SINAPSE | `Edit(.sinapse-ai/core/**)`, `Edit(.sinapse-ai/constitution.md)`, `Edit(bin/sinapse.js)` |
+| Infrastructure | `Bash(terraform apply *)`, `Bash(terraform destroy *)` |
+| Database | `Bash(psql * DROP *)`, `Bash(mysql * DROP *)` |
+| Docker | `Bash(docker rm -f *)`, `Bash(docker system prune *)` |
+
+**Ask rules (prompt before executing):**
+
+```json
+{
+  "ask": [
+    "Bash(git push *)",
+    "Bash(git checkout -- *)",
+    "Bash(git reset --hard *)",
+    "Edit(./package.json)",
+    "Edit(./tsconfig.json)",
+    "Bash(npm install *)",
+    "Bash(npm uninstall *)"
+  ]
+}
+```
+
+### Phase 5: Set MCP Tool Permissions
+
+1. For each configured MCP server, add appropriate permission rules:
+   - Trusted servers: add to allow list (e.g., `MCP(context7)`)
+   - Semi-trusted: add to ask list (e.g., `MCP(filesystem)`)
+   - Blocked: add to deny list (e.g., `MCP(untrusted-server)`)
+2. If enterprise: check `allowedMcpServers` / `deniedMcpServers` managed lists
+3. For Agent permissions:
+   - Allow known safe subagents: `Agent(Explore)`, `Agent(Plan)`
+   - Custom agents: add to allow if trusted, ask if new
+
+---
+
+## Output Format
+
+```markdown
+## Permission Strategy
+
+**Project:** {project-name}
+**Sensitivity:** {level}
+**Team:** {size}
+**Mode:** {selected-mode}
+
+### Rule Summary
+
+| Category | Count | Examples |
+|----------|-------|---------|
+| deny | {N} | .env, secrets, destructive commands |
+| ask | {N} | git push, package.json changes |
+| allow | {N} | npm scripts, git read-only, src/ access |
+
+### Complete Configuration
+
+```json
+{
+  "permissions": {
+    "deny": [ ... ],
+    "ask": [ ... ],
+    "allow": [ ... ],
+    "defaultMode": "{mode}"
+  }
+}
+```
+
+### Evaluation Examples
+
+Show how specific operations will be handled:
+
+| Operation | Matches | Category | Result |
+|-----------|---------|----------|--------|
+| `cat .env` | `Read(./.env)` | deny | BLOCKED |
+| `npm run test` | `Bash(npm run *)` | allow | AUTO-APPROVED |
+| `git push origin main` | `Bash(git push *)` | ask | PROMPTS USER |
+| `edit src/app.ts` | `Edit(src/**)` | allow | AUTO-APPROVED |
+
+### Security Coverage
+
+- [x] Environment files protected
+- [x] Secret directories blocked
+- [x] Destructive commands blocked
+- [x] Pipe-to-shell attacks blocked
+- [x] Certificate/key files protected
+- [ ] {Any gaps flagged here}
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** design a strategy without deny rules for .env and secrets. These are non-negotiable security baselines.
+- **NEVER** add destructive bash commands (rm -rf, format, mkfs) to the allow list.
+- **NEVER** recommend `bypassPermissions` mode for team or enterprise environments.
+- **NEVER** allow `Bash(curl * | bash)` or `Bash(wget * | bash)` patterns -- pipe-to-shell is a known attack vector.
+- **NEVER** put the same pattern in both deny and allow without explaining that deny always wins.
+
+---
+
+## Completion Criteria
+
+- [ ] Security assessment completed with sensitivity profile
+- [ ] Permission mode selected with documented rationale
+- [ ] Deny rules cover all mandatory sensitive patterns
+- [ ] Allow rules enable detected development workflows
+- [ ] Ask rules protect modification of critical config files
+- [ ] MCP tool permissions set for all configured servers
+- [ ] Evaluation examples show how common operations are handled