sinapse-ai 7.1.0 → 7.2.0

package/squads/claude-code-mastery/tasks/create-rules.md

@@ -0,0 +1,206 @@
+# Task: Create Conditional Rules
+
+**Task ID:** CCM-CONFIG-003
+**Version:** 1.0.0
+**Command:** `*create-rules`
+**Orchestrator:** Sigil (config-engineer)
+**Purpose:** Create conditional rules in `.claude/rules/` with proper `paths:` YAML frontmatter for context-efficient loading, ensuring rules only activate when relevant files are being worked on.
+
+---
+
+## Overview
+
+```
+  +------------------+     +------------------+     +------------------+
+  | 1. Identify      | --> | 2. Create Rule   | --> | 3. Write Rule    |
+  |    Rule Need     |     |    File with     |     |    Content       |
+  +------------------+     |    Frontmatter   |     +------------------+
+                            +------------------+          |
+                                                          v
+                            +------------------+     +------------------+
+                            | 5. Test Rule     | <-- | 4. Validate      |
+                            |    Activation    |     |    Rule Loading  |
+                            +------------------+     +------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| rule_name | string | User parameter | Yes | Kebab-case filename (e.g., `api-conventions`) |
+| rule_type | string | User parameter | No | `conditional` (default) or `always-on` |
+| target_paths | array | User parameter or auto-detected | No | Glob patterns for conditional loading |
+| description | string | User parameter | No | Purpose of the rule |
+
+---
+
+## Preconditions
+
+- .claude/ directory exists (or will be created)
+- Understanding of which directories/files the rule should apply to
+- No existing rule file with the same name (or user confirms overwrite)
+
+---
+
+## Execution Phases
+
+### Phase 1: Identify Rule Need
+
+Determine what kind of rule to create:
+
+1. Ask the user what behavior they want to enforce or what context they want to inject
+2. Categorize the rule:
+
+| Category | Example Rules | Typical Paths |
+|----------|---------------|---------------|
+| API conventions | Endpoint patterns, error handling, validation | `src/api/**`, `server/**` |
+| Component patterns | React patterns, styling, props conventions | `src/components/**/*.tsx` |
+| Test conventions | Testing patterns, mock strategies, coverage | `tests/**`, `**/*.test.*` |
+| Database rules | Migration patterns, query conventions, RLS | `migrations/**`, `supabase/**` |
+| Documentation | Doc formatting, README structure, changelog | `docs/**`, `*.md` |
+| Security | Input validation, auth patterns, OWASP | `src/auth/**`, `src/middleware/**` |
+| Configuration | Config file conventions, env var patterns | `*.config.*`, `.env.*` |
+| Always-on | Project-wide conventions (no paths: needed) | (none -- loads always) |
+
+3. If the user is unsure: scan the project structure and suggest rules based on detected directories
+
+### Phase 2: Create Rule File with Frontmatter
+
+1. Determine the file path: `.claude/rules/{rule_name}.md`
+2. For **conditional rules**, generate the `paths:` YAML frontmatter:
+
+```markdown
+---
+paths:
+  - "src/api/**/*.ts"
+  - "src/api/**/*.tsx"
+  - "server/**/*.ts"
+---
+```
+
+**Glob pattern reference:**
+- `*` matches any single path segment
+- `**` matches zero or more path segments (recursive)
+- `*.ts` matches TypeScript files in current directory
+- `**/*.ts` matches TypeScript files recursively
+- `src/{api,server}/**` matches multiple directories
+- `**/*.{ts,tsx}` matches multiple extensions using brace expansion
+
+3. For **always-on rules**, omit the frontmatter entirely (no `---` blocks)
+4. Create subdirectories if organizing by domain: `.claude/rules/frontend/`, `.claude/rules/backend/`
+
+### Phase 3: Write Rule Content
+
+Write the rule body following these guidelines:
+
+1. **Start with a clear header** explaining the rule's purpose
+2. **Use imperative instructions** -- tell Claude what to do, not what to consider
+3. **Be specific and verifiable** -- include code examples when relevant
+4. **Keep rules concise** -- target 20-60 lines per rule file
+5. **Use bullet points** for individual rules
+
+**Rule template:**
+
+```markdown
+---
+paths:
+  - "{glob-patterns}"
+---
+# {Rule Title}
+
+## Conventions
+
+- {Specific, actionable instruction}
+- {Another instruction with example}
+
+## Patterns
+
+When creating {X}, follow this pattern:
+
+```{language}
+{code example}
+```
+
+## Anti-patterns
+
+- Do NOT {specific thing to avoid}
+- Do NOT {another thing to avoid}
+```
+
+### Phase 4: Validate Rule Loading
+
+1. Verify the frontmatter YAML is valid:
+   - Proper `---` delimiters (opening and closing)
+   - `paths:` is a YAML array (each item starts with `- `)
+   - Glob patterns are quoted strings
+   - No trailing whitespace or tab characters in frontmatter
+2. Verify the file is saved in `.claude/rules/` (or a subdirectory)
+3. Check that the glob patterns match actual files in the project:
+   - Run a glob match test against the project structure
+   - Warn if patterns match zero files (possibly incorrect)
+   - Warn if patterns match too many files (overly broad)
+
+### Phase 5: Test Rule Activation
+
+1. Explain to the user how to verify the rule loads:
+   - Open a file matching one of the glob patterns
+   - The rule should appear in Claude's context for that interaction
+   - Rules without paths: frontmatter load on every interaction
+2. Suggest a test prompt that would trigger the rule's instructions
+3. If the rule conflicts with CLAUDE.md content, flag the conflict:
+   - Rules and CLAUDE.md instructions should complement, not contradict
+   - If contradiction exists: recommend removing the instruction from CLAUDE.md (the rule file is more targeted)
+
+---
+
+## Output Format
+
+```markdown
+## Rule Created
+
+**File:** .claude/rules/{rule_name}.md
+**Type:** {conditional | always-on}
+**Lines:** {N}
+
+### Loading Behavior
+
+{For conditional:}
+This rule loads when Claude reads files matching:
+- `{pattern-1}` -- matches {N} files
+- `{pattern-2}` -- matches {N} files
+
+{For always-on:}
+This rule loads on every interaction.
+
+### Content Summary
+
+{1-2 sentence summary of what the rule enforces}
+
+### Verification
+
+Open any file matching the paths above and ask Claude to follow the
+conventions. The rule will be active in that context.
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** create a rule that contradicts instructions in CLAUDE.md without flagging the conflict and recommending resolution.
+- **NEVER** create a conditional rule without testing that its glob patterns match at least one existing file. Warn if zero matches.
+- **NEVER** write a rule file over 100 lines. Split into multiple focused rules instead.
+- **NEVER** include secrets, API keys, or credentials in rule files (they are committed to git).
+- **NEVER** create an always-on rule for content that should be conditional. Large always-on rules waste context budget on every interaction.
+
+---
+
+## Completion Criteria
+
+- [ ] Rule need identified and categorized
+- [ ] File created in .claude/rules/ with correct path
+- [ ] Frontmatter YAML validated (for conditional rules)
+- [ ] Rule content follows the template with specific, actionable instructions
+- [ ] Glob patterns tested against project structure
+- [ ] No conflicts with existing CLAUDE.md instructions

package/squads/claude-code-mastery/tasks/create-team-topology.md

@@ -0,0 +1,258 @@
+# Task: Design Agent Team Configuration
+
+**Task ID:** create-team-topology
+**Version:** 1.0
+**Purpose:** Design and configure a multi-agent team with defined topology, roles, and communication patterns
+**Orchestrator:** @swarm-orqx (Nexus)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Team topology tested with dry-run, all agents load successfully
+
+---
+
+## Overview
+
+This task designs an Agent Team configuration where multiple subagents collaborate on a workload. It covers topology selection, role definition, communication patterns, and isolation strategies.
+
+```
+INPUT (workload_description + team_size + isolation_needs)
+    |
+[PHASE 1: WORKLOAD DECOMPOSITION]
+    -> Analyze the workload for parallelizable units
+    -> Identify shared state requirements
+    -> Determine coordination needs
+    |
+[PHASE 2: ROLE DEFINITION]
+    -> Define each agent's responsibility
+    -> Assign models per role
+    -> Set tool permissions per agent
+    |
+[PHASE 3: AGENT FILE CREATION]
+    -> Create .claude/agents/{name}.md for each member
+    -> Configure frontmatter (name, model, tools)
+    -> Write role-specific instructions
+    |
+[PHASE 4: TOPOLOGY DESIGN]
+    -> Select topology pattern
+    -> Define communication flow
+    -> Set max_turns per agent
+    |
+[PHASE 5: COMMUNICATION PATTERNS]
+    -> Define handoff protocol between agents
+    -> Set up shared context (files, directories)
+    -> Configure completion criteria
+    |
+[PHASE 6: COMPLETION CRITERIA]
+    -> Define what "done" means for each agent
+    -> Define what "done" means for the team
+    -> Plan output aggregation
+    |
+OUTPUT: Agent team files + topology diagram + communication spec
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| workload_description | string | User | yes | Clear description of the full task |
+| team_size | number | User or auto | no | Suggested number of agents (default: auto-detect) |
+| isolation_mode | enum | User | no | shared (default) / worktree / none |
+| topology_preference | enum | User | no | hub-spoke / pipeline / peer / auto |
+| max_budget | string | User | no | Cost constraint (e.g., "keep it cheap") |
+
+---
+
+## Preconditions
+
+1. `.claude/agents/` directory exists
+2. Workload is clearly defined and scoped
+3. At least 2 distinct subtasks identified in the workload
+
+---
+
+## Phase 1: Workload Decomposition
+
+**Goal:** Break the workload into agent-sized units.
+
+### Steps
+
+1.1. Analyze the workload description for distinct, separable concerns.
+1.2. Identify which subtasks can run in parallel vs sequentially.
+1.3. Map shared resources (files, databases, APIs) across subtasks.
+1.4. Determine minimum team size based on distinct concerns.
+
+### Decomposition Checklist
+
+- [ ] Each subtask has a single clear responsibility
+- [ ] Dependencies between subtasks are identified
+- [ ] Shared state conflicts are documented
+- [ ] Parallelization opportunities are marked
+
+---
+
+## Phase 2: Role Definition
+
+**Goal:** Assign clear roles to each agent.
+
+### Steps
+
+2.1. For each subtask, define an agent role:
+
+```yaml
+roles:
+  - name: "{role-name}"
+    responsibility: "{what this agent does}"
+    inputs: "{what it receives}"
+    outputs: "{what it produces}"
+    model: "{opus|sonnet|haiku}"
+    tools: ["{tool1}", "{tool2}"]
+```
+
+2.2. Assign models based on task complexity:
+   - Coordinator/orchestrator: sonnet (needs judgment, not deep analysis)
+   - Complex analysis: opus (architecture, security review)
+   - Code generation: sonnet (standard implementation)
+   - Simple tasks: haiku (formatting, data extraction)
+
+2.3. Verify no two agents have overlapping responsibilities.
+
+---
+
+## Phase 3: Agent File Creation
+
+**Goal:** Create the agent definition files.
+
+### Steps
+
+3.1. For each role from Phase 2, create `.claude/agents/{role-name}.md`.
+3.2. Use the create-agent-definition task format for each file.
+3.3. Include team-specific instructions in each agent:
+   - What other agents exist on the team
+   - Where to write outputs (shared directory)
+   - How to signal completion
+
+---
+
+## Phase 4: Topology Design
+
+**Goal:** Select the right topology for agent interaction.
+
+### Topology Comparison
+
+| Topology | Structure | Best For | Coordination Cost |
+|----------|-----------|----------|-------------------|
+| **Hub-and-Spoke** | One coordinator dispatches to specialists | Mixed tasks, varied complexity | Medium |
+| **Pipeline** | Agent A output feeds Agent B input | Sequential processing, data transformation | Low |
+| **Peer** | All agents work independently, merge at end | Embarrassingly parallel tasks | Low |
+| **Hierarchical** | Multi-level coordinators with sub-teams | Large complex projects | High |
+
+### Selection Decision
+
+```
+Are subtasks independent with no shared state?
+  YES -> Peer topology
+  NO  -> Do subtasks form a sequential chain?
+    YES -> Pipeline topology
+    NO  -> Is there one "brain" coordinating specialists?
+      YES -> Hub-and-Spoke topology
+      NO  -> Hierarchical topology
+```
+
+4.1. Select topology based on decomposition analysis.
+4.2. Document the topology with an ASCII diagram.
+4.3. Set `max_turns` guidance per agent:
+   - Simple tasks: 5-10 turns
+   - Standard tasks: 15-25 turns
+   - Complex tasks: 30-50 turns
+
+---
+
+## Phase 5: Communication Patterns
+
+**Goal:** Define how agents share information.
+
+### Communication Strategies
+
+| Strategy | Mechanism | Isolation Level |
+|----------|-----------|----------------|
+| **File-based** | Agents write to shared directory | Low (same repo) |
+| **Worktree** | Each agent has its own git worktree | High (separate working trees) |
+| **Branch** | Agents work on separate branches | Medium (same repo, different branches) |
+
+### Steps
+
+5.1. Define a shared output directory (e.g., `.claude/team-output/{task-id}/`).
+5.2. Define handoff format (how one agent signals completion):
+   - Write a `{agent-name}-done.md` file with summary and outputs
+   - Or write to a shared `progress.yaml` file
+5.3. Define conflict resolution if agents might modify the same files:
+   - Use worktree isolation for high-risk scenarios
+   - Use file-level ownership for medium-risk
+   - Use merge-at-end for low-risk
+
+---
+
+## Phase 6: Completion Criteria
+
+**Goal:** Define what "done" means.
+
+### Steps
+
+6.1. For each agent, define completion as:
+   - Output files written
+   - Quality check passed (lint, test, etc.)
+   - Completion signal sent
+
+6.2. For the team, define completion as:
+   - All agents report done
+   - Outputs aggregated
+   - Integration test passed (if applicable)
+
+6.3. Define failure handling:
+   - Agent fails -> retry once, then escalate to coordinator
+   - Coordinator fails -> escalate to human
+   - Timeout -> kill agent, report partial results
+
+---
+
+## Output Format
+
+```yaml
+team_topology_result:
+  topology: "{hub-spoke|pipeline|peer|hierarchical}"
+  agents:
+    - name: "{agent-1}"
+      file: ".claude/agents/{agent-1}.md"
+      model: "sonnet-4"
+      role: "{responsibility}"
+    - name: "{agent-2}"
+      file: ".claude/agents/{agent-2}.md"
+      model: "haiku-4"
+      role: "{responsibility}"
+  communication:
+    strategy: "{file-based|worktree|branch}"
+    shared_dir: ".claude/team-output/{task-id}/"
+    handoff_format: "completion-file"
+  completion:
+    all_agents_done: true
+    outputs_aggregated: true
+  diagram: |
+    [Coordinator]
+        |
+    +---+---+
+    |       |
+    [A1]   [A2]
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Workload cannot be decomposed into 2+ distinct subtasks | HALT -- single agent is sufficient |
+| Team size exceeds 6 agents | HALT -- decompose into sub-teams first |
+| All agents need write access to the same files | HALT -- redesign with file ownership or worktree isolation |
+| No clear completion criteria defined | HALT -- define "done" before creating team |
+| Model costs exceed stated budget constraint | HALT -- downgrade models or reduce team size |

package/squads/claude-code-mastery/tasks/diagnose.md

@@ -0,0 +1,166 @@
+# Task: Diagnose Claude Code Question
+
+**Task ID:** CCM-CHIEF-001
+**Version:** 1.0.0
+**Command:** `*diagnose`
+**Orchestrator:** Orion (claude-mastery-chief)
+**Purpose:** Triage Claude Code questions and problems, provide a quick answer, and route to the appropriate specialist agent when domain-specific expertise is needed.
+
+---
+
+## Overview
+
+```
+  User Question
+       |
+       v
+  +------------------+
+  | 1. Parse Request  |
+  |    Extract keywords|
+  +------------------+
+       |
+       v
+  +------------------+
+  | 2. Match Routing  |
+  |    Matrix          |
+  +------------------+
+       |
+       +-------+-------+
+       |               |
+       v               v
+  Cross-cutting    Domain-specific
+       |               |
+       v               v
+  +----------+    +------------------+
+  | 3a. Answer|   | 3b. Quick Answer |
+  |  Directly |   |  + Route to      |
+  +----------+    |  Specialist       |
+       |          +------------------+
+       v               |
+  +------------------+ |
+  | 4. Output Report | <+
+  +------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| question | string | User prompt | Yes | Non-empty natural language question or problem description |
+| context | object | Session state | No | Active story, branch, recent errors if available |
+
+---
+
+## Preconditions
+
+- Claude Code Mastery squad is active with Orion as the entry agent
+- Routing matrix is loaded from the agent definition (triage.routing_matrix)
+- All 7 specialist agents are registered in config.yaml
+
+---
+
+## Execution Phases
+
+### Phase 1: Analyze Request (Keyword Extraction)
+
+1. Parse the user's question or problem description
+2. Extract primary keywords and intent signals
+3. Identify the request category:
+   - Is it a "how to" question?
+   - Is it a debugging/troubleshooting problem?
+   - Is it a setup/configuration request?
+   - Is it a conceptual/comparison question?
+4. Note any secondary domains that may be relevant
+
+### Phase 2: Match Against Routing Matrix
+
+Apply keyword matching against the 7 specialist domains:
+
+| Domain | Keywords | Route To | Persona |
+|--------|----------|----------|---------|
+| hooks | hook, pre_tool_use, post_tool_use, lifecycle, intercept, block, exit code, automation pipeline, pre_compact, notification, damage control | hooks-architect | Latch |
+| mcp | mcp, server, tool search, stdio, sse, http streamable, mcp__, context7, exa, docker gateway, add server | mcp-integrator | Piper |
+| subagents | subagent, agent team, swarm, teammate, worktree, parallel, background agent, spawn, multi-agent, TeammateTool | swarm-orqx | Nexus |
+| config | settings, permission, CLAUDE.md, rules, sandbox, managed, enterprise, allow, deny, keybinding, context window, compaction | config-engineer | Sigil |
+| skills | skill, command, plugin, SKILL.md, slash command, context engineering, spec-driven, .claude/commands, .claude/skills, marketplace | skill-craftsman | Anvil |
+| integration | integrate, repository, project setup, CI/CD, headless, brownfield, monorepo, SINAPSE, git workflow | project-integrator | Conduit |
+| roadmap | update, changelog, version, roadmap, new feature, what changed, migration, upgrade, adoption | roadmap-sentinel | Vigil |
+
+**Scoring rules:**
+- Count keyword matches per domain
+- If one domain scores significantly higher (2+ matches above others), route there
+- If multiple domains tie or the question spans domains, treat as cross-cutting
+- If no domain matches strongly, treat as cross-cutting (Orion answers directly)
+
+### Phase 3a: Cross-Cutting Answer (Direct)
+
+If the question is cross-cutting or general:
+
+1. Synthesize knowledge from the quick_reference section and SINAPSE awareness
+2. Provide a complete, actionable answer
+3. Reference relevant specialist agents the user can consult for deeper exploration
+4. Include code snippets, configuration examples, or reference tables as appropriate
+
+### Phase 3b: Domain-Specific Answer (Quick + Route)
+
+If the question maps to a specific domain:
+
+1. **Provide a quick answer first** -- Never route without giving immediate value
+   - Answer the question at a surface level (3-5 lines minimum)
+   - Include a concrete example (code snippet, config block, or command)
+2. **Route to the specialist** for deeper expertise:
+   - Name the specialist agent and persona
+   - Explain what additional depth the specialist can provide
+   - Provide the activation command: `@claude-code-mastery:{agent-id}`
+   - Suggest a specific specialist command if applicable (e.g., `*create-hook`, `*audit-settings`)
+
+### Phase 4: Confidence Assessment
+
+Rate the diagnosis confidence:
+
+| Confidence | Criteria | Action |
+|------------|----------|--------|
+| HIGH | 3+ keyword matches in one domain, clear intent | Route with confidence |
+| MEDIUM | 1-2 matches, ambiguous intent | Provide answer + suggest 2 possible specialists |
+| LOW | No clear domain match | Answer directly, ask clarifying question |
+
+---
+
+## Output Format
+
+```markdown
+## Diagnosis
+
+**Category:** {domain-name | cross-cutting}
+**Confidence:** {HIGH | MEDIUM | LOW}
+**Specialist:** {persona-name} ({agent-id}) | Direct Answer
+
+### Quick Answer
+
+{3-10 line answer with concrete example}
+
+### Recommended Next Step
+
+{Route instruction OR follow-up question for clarification}
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** route to a specialist without providing at least a quick answer first. The user must receive immediate value from every interaction with Orion.
+- **NEVER** route when confidence is LOW -- ask a clarifying question instead.
+- **NEVER** load a specialist agent file during diagnosis. Only provide routing instructions for the user to activate the specialist.
+- **NEVER** guess the domain when keywords are ambiguous -- synthesize a cross-cutting answer and let the user refine.
+
+---
+
+## Completion Criteria
+
+- [ ] User question parsed and keywords extracted
+- [ ] Routing matrix consulted with scored results
+- [ ] Quick answer provided with concrete example
+- [ ] Specialist routing provided (if domain-specific)
+- [ ] Confidence level stated in output