sinapse-ai 1.0.0

package/squad-claude/tasks/sandbox-setup.md

@@ -0,0 +1,75 @@
+---
+task: sandbox-setup
+responsavel: "@roadmap-sentinel"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Sandbox Setup
+
+## Objective
+
+Set up a sandbox environment for safely testing new Claude Code features, experimental configurations, and upgrades before applying them to production projects. Ensure isolation from production codebases.
+
+## Inputs
+
+- Features to test (new hooks, MCP servers, configuration changes)
+- Production configuration (to replicate baseline)
+- Isolation requirements (separate repo? branch? Docker container?)
+- Test scenarios to validate
+
+## Steps
+
+1. **Create Isolated Environment** — Set up a sandbox: clone the production repo to a test directory, create a test branch, or spin up a Docker container. Ensure no writes to production.
+2. **Replicate Production Config** — Copy production .claude/ configuration to the sandbox. This establishes the baseline for comparison.
+3. **Apply Experimental Changes** — Add the new features, configurations, or upgrades to be tested. Document exactly what was changed from baseline.
+4. **Design Test Scenarios** — For each change, create specific test scenarios: trigger conditions, expected behavior, failure cases, and performance benchmarks.
+5. **Execute Tests** — Run each test scenario in the sandbox. Record results: passed/failed, performance impact, unexpected behaviors, error messages.
+6. **Compare with Baseline** — Run the same scenarios with the original configuration. Compare results to isolate the impact of the changes.
+7. **Generate Report** — Produce a go/no-go recommendation with evidence from testing. Include rollback instructions if the feature is adopted and problems emerge later.
+
+## Quality Gates
+
+- Sandbox must be fully isolated from production
+- All test scenarios must be executed
+- Performance comparison must include baseline measurements
+- Report must include explicit go/no-go recommendation
+
+## Output Format
+
+```markdown
+# Sandbox Test Report
+
+## Feature Tested: {name}
+
+## Environment
+- Isolation: {method}
+- Baseline: {production config version}
+- Changes: {list}
+
+## Test Results
+| Scenario | Expected | Actual | Status |
+|----------|----------|--------|--------|
+
+## Performance Impact
+| Metric | Baseline | With Change | Delta |
+|--------|----------|-------------|-------|
+
+## Recommendation: {GO / NO-GO}
+## Rationale: {evidence-based}
+```

package/squad-claude/tasks/setup-repository.md

@@ -0,0 +1,58 @@
+---
+task: setup-repository
+responsavel: "@project-integrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Setup Repository
+
+## Objective
+
+Set up a new repository with Claude Code configuration from scratch, creating the optimal directory structure, configuration files, rules, and initial hooks for the specified technology stack and team size.
+
+## Inputs
+
+- Repository name and description
+- Technology stack (language, framework, database)
+- Team size (solo / small team / large team)
+- Automation level (minimal / standard / full)
+- MCP integrations needed
+- Git hosting (GitHub, GitLab, Bitbucket)
+
+## Steps
+
+1. **Create Directory Structure** — Set up .claude/ directory with settings.json, rules/ subdirectory, and any template files. Create CLAUDE.md at project root.
+2. **Generate CLAUDE.md** — Write project-specific CLAUDE.md with stack information, coding conventions, directory structure guide, common commands, and anti-patterns.
+3. **Configure Settings** — Create settings.json with permissions tailored to team size and automation level. Solo developers get more auto-approve; large teams get stricter controls.
+4. **Create Initial Rules** — Generate rules files for the primary file patterns: source code, tests, configuration files, documentation. Use `paths:` frontmatter.
+5. **Set Up Hooks** — Based on automation level: minimal (no hooks), standard (auto-lint, auto-format), full (auto-lint, auto-test, security gates, notification routing).
+6. **Configure MCP** — Add MCP server configurations for requested integrations. Verify each server connects successfully.
+7. **Add .gitignore Entries** — Ensure .claude/settings.local.json and any local-only files are gitignored. Keep .claude/settings.json and rules/ tracked.
+8. **Generate README Section** — Add a "Claude Code Setup" section to README.md explaining the AI-assisted development workflow for the project.
+
+## Quality Gates
+
+- All generated files must be valid (JSON valid, Markdown well-formed)
+- Permission model must match team size requirements
+- At least one smoke test of Claude Code in the new repo must pass
+- .gitignore must protect local settings and secrets
+
+## Output Format
+
+File manifest with all created files and a quickstart guide for team members.

package/squad-claude/tasks/setup-wizard.md

@@ -0,0 +1,78 @@
+---
+task: setup-wizard
+responsavel: "@cm-orchestrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Setup Wizard
+
+## Objective
+
+Guide the creation of a complete Claude Code setup for a new or existing project. Orchestrate all specialist agents to produce configuration, hooks, MCP integrations, rules, and CLAUDE.md files tailored to the project's stack and team.
+
+## Inputs
+
+- Project type (greenfield / brownfield)
+- Technology stack (language, framework, database, etc.)
+- Team size and structure
+- Desired automation level (minimal / standard / full)
+- Existing CI/CD pipeline (if any)
+- MCP servers needed (Supabase, GitHub, Figma, etc.)
+
+## Steps
+
+1. **Classify Project** — Determine if greenfield or brownfield. For brownfield, delegate initial assessment to `@project-integrator` via `brownfield-setup` task.
+2. **Design Configuration** — Delegate to `@config-engineer` to create .claude/settings.json, CLAUDE.md, and .claude/rules/ structure via `configure-settings` and `claude-md-engineer` tasks.
+3. **Plan MCP Integration** — Delegate to `@mcp-integrator` to design MCP server setup via `mcp-integration-plan` task based on required integrations.
+4. **Design Hooks** — Delegate to `@hooks-architect` to create automation hooks via `hook-designer` task based on desired automation level.
+5. **Optimize Context** — Delegate to `@skill-craftsman` to review and optimize context footprint via `optimize-context` task.
+6. **Validate Setup** — Run `audit-setup` on the completed configuration to verify all dimensions meet minimum thresholds.
+7. **Generate Setup Summary** — Compile all outputs into a single setup document with file manifest and next steps.
+
+## Quality Gates
+
+- All generated files must pass syntax validation
+- Settings.json must have no conflicting permissions
+- CLAUDE.md total token footprint must be under budget (context efficiency >= 3/5)
+- At least 3 hooks configured for standard automation level
+- All specified MCP servers must have valid configurations
+
+## Output Format
+
+```markdown
+# Claude Code Setup Complete
+
+## Files Created
+- .claude/settings.json
+- CLAUDE.md
+- .claude/rules/*.md
+- .claude/settings.local.json (template)
+
+## MCP Servers Configured
+- [ ] Server 1: status
+- [ ] Server 2: status
+
+## Hooks Installed
+- PreToolUse: ...
+- PostToolUse: ...
+
+## Next Steps
+1. ...
+2. ...
+```

package/squad-claude/tasks/slash-command-library-design.md

@@ -0,0 +1,102 @@
+---
+task: slash-command-library-design
+responsavel: "@config-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Slash Command Library Design
+
+## Objective
+
+Design a comprehensive library of custom slash commands (Claude Code custom commands) for a project or organization. Create reusable command definitions that encode team workflows, enforce standards, and accelerate common development tasks through parameterized prompt templates.
+
+## Pre-Conditions
+
+- Common team workflows and repetitive tasks identified
+- Claude Code custom commands feature understood (/.claude/commands/ structure)
+- Team roles and their most frequent Claude Code interactions documented
+- Naming convention for commands established
+- Output format standards defined
+
+## Steps
+
+1. **Audit Common Workflows** — Interview team members or review conversation history to identify the 20 most common tasks: creating components, writing tests, reviewing code, updating documentation, debugging issues, creating migrations, refactoring patterns, and generating boilerplate.
+2. **Categorize Commands** — Group commands by function: scaffolding (create new files/components), analysis (review, audit, assess), transformation (refactor, migrate, update), documentation (generate docs, update changelog), and workflow (run pipelines, coordinate tasks).
+3. **Design Command Schema** — For each command, define: name (verb-noun, e.g., create-component), description (one-line purpose), parameters (with types and defaults), prompt template (the instruction Claude receives), and expected output format.
+4. **Write Prompt Templates** — For each command, write the prompt template that will be injected when the command is invoked. Include: clear objective, step-by-step instructions, output format specification, quality criteria, and parameter substitution points (using $ARGUMENTS or named parameters).
+5. **Implement Parameter Handling** — Design how commands accept and use parameters: positional arguments ($ARGUMENTS), named flags (--name value), defaults for optional parameters, and validation rules. Document parameter syntax for each command.
+6. **Create Command Hierarchies** — Organize commands into namespaces: /project:create-component, /project:create-test, /review:code, /review:security, /docs:generate. This prevents naming collisions and makes discovery easier.
+7. **Build Composition Patterns** — Design commands that can chain together: /scaffold:feature creates files, then /test:generate creates tests for them, then /docs:component documents them. Define the data flow between composed commands.
+8. **Add Guard Rails** — Include safety checks in command templates: verify preconditions before executing (required files exist, correct directory), validate parameters, and include rollback instructions for destructive commands.
+9. **Create Discovery System** — Build a command index with: command name, category, description, usage example, and parameter reference. Make it accessible via a meta-command like /help or /commands.
+10. **Test All Commands** — Execute each command with: standard parameters (happy path), edge case parameters (empty, very long, special characters), missing required parameters, and incorrect parameter types. Verify output quality and format compliance.
+11. **Write User Guide** — Document: how to use commands, how to add new commands, naming conventions, parameter syntax, and troubleshooting common issues.
+
+## Output
+
+```markdown
+# Slash Command Library
+
+## Command Index
+| Command | Category | Description | Parameters |
+|---------|----------|-------------|-----------|
+
+## Command Definitions
+
+### /{namespace}:{command-name}
+**Description:** {what it does}
+**Parameters:**
+- `{param}` ({type}, {required/optional}): {description}
+
+**Prompt Template:**
+```
+{complete prompt template with $ARGUMENTS placeholders}
+```
+
+**Usage Example:**
+```
+/{namespace}:{command-name} {example arguments}
+```
+
+**Expected Output:** {description of output format}
+
+## Composition Patterns
+| Workflow | Commands | Data Flow |
+|----------|----------|-----------|
+
+## File Structure
+```
+.claude/commands/
+├── {namespace}/
+│   ├── {command-name}.md
+│   └── {command-name}.md
+```
+
+## User Guide
+{usage instructions}
+```
+
+## Quality Criteria
+
+- Library must include at least 15 commands covering all 5 categories
+- Every command must produce consistent output across 3+ test runs
+- Prompt templates must be under 500 tokens each (concise but complete)
+- Command namespaces must have no naming collisions
+- Parameter validation must catch invalid inputs before execution
+- Discovery system must enable finding any command within 10 seconds

package/squad-claude/tasks/system-prompt-design.md

@@ -0,0 +1,87 @@
+---
+task: system-prompt-design
+responsavel: "@skill-craftsman"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# System Prompt Design
+
+## Objective
+
+Design effective system prompts for AI agents that establish clear personas, behavioral boundaries, output formats, and domain expertise. Produce production-ready system prompts with structured sections, tested against edge cases and adversarial inputs.
+
+## Pre-Conditions
+
+- Clear definition of the agent's role and domain
+- Target use cases and user interaction patterns documented
+- Output format requirements specified
+- Known constraints and safety boundaries identified
+- Access to example interactions for validation
+
+## Steps
+
+1. **Define Agent Identity** — Establish the agent's persona: name, role, expertise domain, communication style (formal/casual, verbose/concise), and authority level. Document what the agent IS and IS NOT responsible for.
+2. **Map Behavioral Boundaries** — Define explicit rules: what the agent must always do, must never do, and should do when uncertain. Use MUST/MUST NOT/SHOULD/SHOULD NOT language for clarity.
+3. **Structure the Prompt Skeleton** — Organize the system prompt into sections: Identity, Core Instructions, Behavioral Rules, Output Format, Error Handling, Examples. Use markdown headers and tables for scannability.
+4. **Write Core Instructions** — Draft the main behavioral instructions. Each instruction should be specific, actionable, and testable. Avoid vague directives like "be helpful" — instead specify "respond with code examples when the user asks how to implement something."
+5. **Design Output Format Specifications** — Define exact output structures: JSON schemas, markdown templates, code block conventions, or free-form guidelines. Include examples of correct and incorrect outputs.
+6. **Add Conditional Logic** — Write branching instructions for different scenarios: "If the user asks about X, respond with Y format. If the input contains Z, first validate before proceeding."
+7. **Implement Safety Rails** — Add guardrails for edge cases: handling off-topic requests, refusing unsafe operations, escalating to humans, dealing with ambiguous inputs.
+8. **Write Few-Shot Examples** — Include 2-3 input/output examples that demonstrate ideal behavior. Cover the happy path, an edge case, and a boundary case.
+9. **Optimize Token Efficiency** — Review the prompt for redundancy and verbosity. Compress without losing clarity. Convert paragraphs to bullet points or tables where appropriate. Target minimum viable token count.
+10. **Test Against Edge Cases** — Validate the prompt against adversarial inputs, ambiguous requests, out-of-scope questions, and multi-step interactions. Document failures and refine.
+11. **Version and Document** — Assign a version number, document the design rationale, list known limitations, and create a changelog template for future iterations.
+
+## Output
+
+```markdown
+# System Prompt: {Agent Name}
+
+## Version
+v{X.Y} — {date}
+
+## Prompt Content
+{complete system prompt text, ready to paste}
+
+## Design Rationale
+| Section | Rationale |
+|---------|-----------|
+| {section} | {why this design choice} |
+
+## Test Results
+| Scenario | Input | Expected Output | Actual | Pass? |
+|----------|-------|-----------------|--------|-------|
+
+## Token Count
+- Total tokens: {count}
+- Sections breakdown: {per-section counts}
+
+## Known Limitations
+- {limitation 1}
+- {limitation 2}
+```
+
+## Quality Criteria
+
+- System prompt must produce consistent behavior across 10+ test interactions
+- Token count must be within budget (specified per project)
+- All MUST/MUST NOT rules must be verifiable in testing
+- Output format specifications must include at least one concrete example
+- Safety rails must handle at least 5 common edge case categories
+- Prompt must be self-contained (no external dependencies for core behavior)

package/squad-claude/tasks/tool-orchestration-pattern.md

@@ -0,0 +1,98 @@
+---
+task: tool-orchestration-pattern
+responsavel: "@mcp-integrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Tool Orchestration Pattern
+
+## Objective
+
+Design tool orchestration patterns that coordinate multiple MCP tools and native Claude Code tools into efficient workflows. Define sequencing rules, parallel execution strategies, error propagation chains, and fallback hierarchies for complex multi-tool operations.
+
+## Pre-Conditions
+
+- Available tools inventoried (native + MCP tools)
+- Target workflows requiring multi-tool coordination identified
+- Tool dependencies and data flow requirements mapped
+- Performance requirements (latency budgets) established
+- Error handling requirements per workflow defined
+
+## Steps
+
+1. **Map Tool Capabilities** — Create a capability matrix of all available tools: what each tool does, its input/output types, latency profile (fast < 1s, medium 1-5s, slow > 5s), reliability rating, and side effects (read-only vs. mutating).
+2. **Identify Orchestration Scenarios** — Document workflows that require multiple tools: code analysis (Read + Grep + Bash), deployment (Git + CI + Notification), research (WebSearch + Read + Write), and data pipeline (Query + Transform + Store).
+3. **Design Sequencing Patterns** — For each scenario, determine the execution order: sequential (output of tool A feeds tool B), parallel (tools A and B run independently, results merged), conditional (tool B runs only if tool A returns X), and iterative (tool A runs until condition met).
+4. **Define Data Flow Contracts** — Specify how data passes between tools: direct piping (output schema matches input schema), transformation (intermediate mapping step), aggregation (multiple outputs combined), and filtering (subset of output forwarded).
+5. **Build Parallel Execution Groups** — Identify tools that can run simultaneously within each workflow. Group independent tool calls for parallel execution. Define synchronization points where parallel branches must converge before proceeding.
+6. **Design Error Propagation** — Define how errors cascade through the orchestration: fail-fast (abort entire workflow), fail-safe (skip failed tool, continue with partial data), retry-then-fail (retry N times with backoff), and fallback (switch to alternative tool).
+7. **Create Fallback Hierarchies** — For critical operations, define tool fallback chains: primary tool fails -> try secondary tool -> try manual workaround -> escalate. Each fallback must produce compatible output for downstream tools.
+8. **Implement Circuit Breakers** — Design circuit breaker patterns for unreliable tools: track failure rate over a sliding window, open circuit after N consecutive failures, attempt half-open after cooldown period, close circuit on success.
+9. **Optimize for Token Efficiency** — Minimize unnecessary tool calls: cache results for reuse within the workflow, batch related operations (multiple file reads in one call), and avoid re-reading data that is already in context.
+10. **Document Pattern Library** — Create a reusable pattern library with: pattern name, trigger conditions, tool sequence diagram, data flow, error handling strategy, and performance characteristics. Include code-level examples.
+
+## Output
+
+```markdown
+# Tool Orchestration Patterns
+
+## Tool Capability Matrix
+| Tool | Type | Latency | Reliability | Side Effects |
+|------|------|---------|------------|-------------|
+
+## Orchestration Patterns
+
+### Pattern: {name}
+**Trigger:** {when to use this pattern}
+**Tools:** {list of tools involved}
+**Sequence:**
+1. {step} -> {tool} -> {output}
+2. {step} -> {tool} -> {output}
+
+**Data Flow:**
+{tool A} --{data type}--> {tool B} --{data type}--> {tool C}
+
+**Error Handling:** {strategy}
+**Fallback:** {alternative path}
+
+**Performance:**
+- Expected latency: {ms}
+- Token cost: {estimate}
+
+## Parallel Execution Groups
+| Workflow | Parallel Group | Tools | Sync Point |
+|----------|---------------|-------|-----------|
+
+## Circuit Breaker Configuration
+| Tool | Failure Threshold | Cooldown | Fallback |
+|------|------------------|----------|----------|
+
+## Anti-Patterns
+| Anti-Pattern | Problem | Correct Approach |
+|-------------|---------|-----------------|
+```
+
+## Quality Criteria
+
+- At least 5 distinct orchestration patterns must be documented
+- Every pattern must include error handling strategy and at least one fallback
+- Parallel execution groups must be validated for no data dependencies
+- Circuit breaker thresholds must be justified with expected failure rates
+- Token efficiency optimizations must be quantified (estimated savings vs. naive approach)
+- Anti-patterns section must include at least 3 common mistakes with corrections

package/squad-claude/tasks/worktree-strategy.md

@@ -0,0 +1,77 @@
+---
+task: worktree-strategy
+responsavel: "@swarm-orchestrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Worktree Strategy
+
+## Objective
+
+Design a Git worktree isolation strategy for parallel Claude Code agents, defining branch naming conventions, worktree lifecycle management, merge protocols, and cleanup procedures.
+
+## Inputs
+
+- Number of parallel agents planned
+- Branch strategy (feature branches, trunk-based, etc.)
+- Base branch for worktrees
+- Merge conflict likelihood (low/medium/high based on file overlap)
+- Disk space constraints
+
+## Steps
+
+1. **Assess Worktree Need** — Determine if worktrees are necessary. If agents work on completely separate files on the same branch, worktrees add unnecessary overhead. If agents modify overlapping areas, worktrees provide essential isolation.
+2. **Design Branch Naming Convention** — Define a pattern: `agent/{agent-name}/{feature-slug}` or `parallel/{task-id}/{unit-number}`. Must be sortable and identifiable.
+3. **Define Worktree Lifecycle** — Create -> Configure -> Execute -> Verify -> Merge -> Cleanup. Each phase must have explicit entry/exit criteria.
+4. **Plan Merge Protocol** — Define merge order (least conflicts first), conflict resolution strategy (agent re-merge, human review, or automated resolution), and verification steps post-merge.
+5. **Design Cleanup Procedure** — Automatic worktree removal after successful merge. Handle orphaned worktrees (agent failure without cleanup). Include disk space monitoring.
+6. **Handle Edge Cases** — Plan for: agent failure mid-work, merge conflicts that require human intervention, disk space exhaustion, and worktree corruption.
+7. **Generate Commands** — Produce the exact git commands for each lifecycle phase: create, configure, merge, and cleanup.
+
+## Quality Gates
+
+- Branch naming convention must be consistent and machine-parseable
+- Merge protocol must handle all identified conflict scenarios
+- Cleanup procedure must leave no orphaned worktrees or branches
+- Disk space impact must be estimated and within constraints
+
+## Output Format
+
+```markdown
+# Worktree Strategy: {project}
+
+## Branch Naming
+Pattern: `{pattern}`
+
+## Lifecycle
+| Phase | Command | Criteria |
+|-------|---------|----------|
+| Create | git worktree add ... | ... |
+| Merge | git merge ... | ... |
+| Cleanup | git worktree remove ... | ... |
+
+## Merge Protocol
+{ordered steps}
+
+## Edge Case Handling
+{scenarios and responses}
+
+## Estimated Disk Impact
+{size per worktree x number of worktrees}
+```

package/squad-claude/workflows/optimization-cycle.yaml

@@ -0,0 +1,98 @@
+name: optimization-cycle
+version: "1.0.0"
+description: "4-phase workflow for optimizing an existing Claude Code setup: Diagnose, Optimize, Test, Document."
+squad: squad-claude
+trigger: manual
+phases:
+  - name: "Phase 1: Diagnose"
+    description: "Identify performance bottlenecks, context waste, and configuration issues"
+    agents:
+      - "@cm-orchestrator"
+      - "@skill-craftsman"
+    tasks:
+      - diagnose
+      - context-rot-audit
+      - audit-hooks
+      - audit-settings
+    inputs:
+      - project_root: "path to project"
+      - pain_points: "reported issues or symptoms"
+    outputs:
+      - diagnosis_report: "Root cause analysis"
+      - rot_report: "Context rot findings"
+      - hooks_audit: "Hooks audit report"
+      - settings_audit: "Settings audit report"
+    gate:
+      condition: "All diagnostic reports generated with actionable findings"
+      on_fail: "Expand diagnostic scope if no findings"
+
+  - name: "Phase 2: Optimize"
+    description: "Apply optimizations based on diagnostic findings"
+    agents:
+      - "@skill-craftsman"
+      - "@config-engineer"
+      - "@hooks-architect"
+    tasks:
+      - optimize-context
+      - optimize-workflow
+      - configure-settings
+      - hook-designer
+    inputs:
+      - diagnosis_report: "from Phase 1"
+      - rot_report: "from Phase 1"
+      - hooks_audit: "from Phase 1"
+      - settings_audit: "from Phase 1"
+    outputs:
+      - context_optimization: "Updated config files with reduced token footprint"
+      - workflow_optimization: "Improved interaction patterns and extracted skills"
+      - updated_settings: "Fixed settings.json"
+      - updated_hooks: "New or improved hooks"
+    gate:
+      condition: "Context token footprint reduced by >= 15% AND no essential info lost"
+      on_fail: "Review optimizations for over-aggressive trimming"
+
+  - name: "Phase 3: Test"
+    description: "Validate optimizations in a sandbox before applying to production"
+    agents:
+      - "@roadmap-sentinel"
+      - "@cm-orchestrator"
+    tasks:
+      - sandbox-setup
+      - audit-setup
+    inputs:
+      - optimized_configs: "from Phase 2"
+      - baseline_configs: "original pre-optimization configs"
+    outputs:
+      - sandbox_report: "Test results comparing baseline vs optimized"
+      - validation_audit: "Post-optimization audit scores"
+    gate:
+      condition: "Sandbox tests pass AND audit score improved from baseline"
+      on_fail: "Roll back problematic optimizations, re-test"
+
+  - name: "Phase 4: Document"
+    description: "Document all changes and update project knowledge"
+    agents:
+      - "@skill-craftsman"
+      - "@config-engineer"
+    tasks:
+      - claude-md-engineer
+      - optimize-context
+    inputs:
+      - all_changes: "from Phases 2-3"
+      - sandbox_report: "from Phase 3"
+    outputs:
+      - updated_claude_md: "Refreshed CLAUDE.md reflecting optimizations"
+      - optimization_changelog: "Record of all changes made"
+    gate:
+      condition: "Documentation complete AND CLAUDE.md within token budget"
+      on_fail: "Trim documentation to meet token budget"
+
+completion:
+  success_criteria: "All 4 phases complete, audit score improved, context reduced >= 15%"
+  deliverables:
+    - "Optimized configuration files"
+    - "Context rot eliminated"
+    - "Workflow improvements documented"
+    - "Sandbox test evidence"
+    - "Updated CLAUDE.md"
+    - "Optimization changelog"