aiox-core 5.0.5 → 5.0.8

package/pro/squads/claude-code-mastery/tasks/mcp-workflow.md

@@ -0,0 +1,330 @@
+# Task: MCP Server Management Workflow
+
+**Task ID:** mcp-workflow
+**Version:** 1.1
+**Purpose:** Discover, evaluate, configure, and validate MCP servers for a project's tech stack using the current Claude Code MCP surfaces and policy constraints
+**Orchestrator:** @mcp-integrator (Piper)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Fully tested MCP integration with documented context budget, ownership, and policy fit
+
+## Contrato SINKRA
+
+task: mcp-workflow
+atomic_layer: Atom
+executor: mcp-integrator
+Domain: Operational
+accountability_token: TK-CCM-ACC-001
+Input:
+- mcp_requirement
+- tooling_context
+- context_budget
+Output:
+- mcp-integration-report
+- mcp-config
+output_schema: mcp-config
+Pre-Conditions:
+- Contexto do projeto disponível e legível
+- Artefatos de referência acessíveis ao executor
+- Critério de sucesso entendido antes da execução
+Post-Conditions:
+- Output publicado em formato auditável
+- Próximo passo explícito ou handoff emitido
+- Decisões relevantes registradas no artefato final
+Performance:
+- Execução em uma sessão sem falha silenciosa
+- Thresholds e veto conditions respeitados
+- Resultado acionável para o próximo executor
+Completion Criteria:
+- Executor único definido
+- Inputs e outputs explícitos
+- Critério final verificável no artefato entregue
+
+---
+
+
+## Overview
+
+This task guides the complete lifecycle of MCP server management: from discovering which servers benefit the project, through evaluating their context budget impact, to configuring and testing them in Claude Code.
+
+```
+INPUT (project_tech_stack + current_mcps)
+    |
+[PHASE 1: DISCOVERY]
+    -> Scan project for frameworks, languages, services
+    -> Match against known MCP server catalog
+    -> Identify gaps in current tooling
+    |
+[PHASE 2: CONTEXT BUDGET EVALUATION]
+    -> Calculate token cost per MCP server
+    -> Compare total budget against model limits
+    -> Recommend add/remove decisions
+    |
+[PHASE 3: CONFIGURATION]
+    -> Choose config surface (.mcp.json vs shared/global settings vs enterprise managed)
+    -> Preserve ownership and dedup rules
+    -> Write MCP entries to the correct surface
+    |
+[PHASE 4: TRANSPORT SELECTION]
+    -> Evaluate local vs remote requirements
+    -> Configure transport parameters
+    -> Set environment variables and secrets
+    |
+[PHASE 5: TOOL VALIDATION]
+    -> Test each MCP server's tool availability
+    -> Verify tool responses with sample calls
+    -> Document available tools per server
+    |
+[PHASE 6: DOCUMENTATION]
+    -> Update CLAUDE.md with MCP usage rules
+    -> Create tool selection priority table
+    -> Document CLI-first vs MCP decision tree
+    |
+OUTPUT: Configured MCP servers + context budget report + CLAUDE.md updates
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Auto-detect | yes | Valid directory with package.json or equivalent |
+| tech_stack | array | Scan or user | yes | List of frameworks/languages in use |
+| current_mcps | object | .mcp.json + settings layers + managed-mcp.json | no | Existing MCP configuration |
+| context_budget_limit | number | User or default | no | Max tokens for MCP overhead (default: 10000) |
+
+---
+
+## Preconditions
+
+1. Claude Code is installed and operational in the project
+2. `.mcp.json`, `.claude/settings.json`, `~/.claude/settings.json`, or `managed-mcp.json` is accessible as appropriate
+3. User has access to install MCP server binaries (npm, pip, docker)
+4. Network access for remote MCP servers (if applicable)
+
+---
+
+## Phase 1: Discovery
+
+**Goal:** Identify which MCP servers would benefit this project.
+
+### Steps
+
+1.1. Scan the project root for tech stack indicators:
+   - `package.json` -> Node.js ecosystem (look for React, Next.js, Express, etc.)
+   - `requirements.txt` / `pyproject.toml` -> Python ecosystem
+   - `docker-compose.yml` -> Container-based services
+   - `.env` / `supabase/` -> Supabase/database usage
+   - `playwright.config.*` -> Browser testing
+
+1.2. Cross-reference detected stack against MCP server catalog:
+
+| Tech Stack Signal | Recommended MCP | Purpose |
+|-------------------|----------------|---------|
+| Supabase project | supabase | Database operations, migrations |
+| Any web project | playwright/browser | UI testing, screenshots |
+| Research-heavy | exa | Web search, company research |
+| Any framework | context7 | Library documentation lookup |
+| Docker services | desktop-commander | Container management |
+| GitHub repo | github-cli (native) | PR/issue management |
+
+1.3. List current MCP servers from `.mcp.json`, settings layers, and enterprise policy surfaces; identify gaps and current ownership (manual, plugin, enterprise).
+
+---
+
+## Phase 2: Context Budget Evaluation
+
+**Goal:** Quantify the token cost of each MCP server.
+
+### Context Budget Math
+
+Each MCP server adds to the system prompt:
+- **Server registration:** ~200 tokens (name, description, connection info)
+- **Tool definitions:** ~100-400 tokens per tool (name, description, parameters, schema)
+- **Typical server:** 600-2000 tokens total
+
+### Budget Calculation
+
+```
+Total MCP Cost = SUM(server_tool_count * avg_tokens_per_tool + 200)
+
+Example:
+  playwright (15 tools)  = 15 * 150 + 200 = 2,450 tokens
+  context7 (2 tools)     = 2 * 150 + 200  = 500 tokens
+  exa (1 tool)           = 1 * 150 + 200  = 350 tokens
+  supabase (5 tools)     = 5 * 150 + 200  = 950 tokens
+  ---
+  TOTAL                  = 4,250 tokens (~2% of 200K context)
+```
+
+### Decision Framework
+
+| Total MCP Budget | Recommendation |
+|-----------------|---------------|
+| < 5,000 tokens | Green -- add freely |
+| 5,000-10,000 tokens | Yellow -- evaluate each addition |
+| > 10,000 tokens | Red -- remove low-value servers |
+
+2.1. Calculate token cost for each proposed MCP server.
+2.2. Sum total and compare against budget limit.
+2.3. If over budget, rank servers by value-per-token and recommend removals.
+
+---
+
+## Phase 3: Configuration
+
+**Goal:** Write MCP server configuration to the appropriate location.
+
+### Config Surface Decision
+
+| Scope | Primary Surface | When to Use |
+|-------|-----------------|-------------|
+| Project-owned server registry | `.mcp.json` | Default choice for manual, project-scoped MCP server definitions |
+| Shared project settings | `.claude/settings.json` | Permissions, hooks, and team defaults that complement MCP usage |
+| User/global defaults | `~/.claude/settings.json` | Personal defaults across projects; avoid storing project-owned server registry here unless intentionally personal |
+| Enterprise-managed policy | `managed-mcp.json` | Organization-enforced MCP allow/deny policy; can take exclusive control |
+
+### Steps
+
+3.1. Determine scope for each MCP server.
+3.2. Inspect `.mcp.json`, project settings, user settings, and `managed-mcp.json` before editing anything.
+3.3. If enterprise MCP config is active, do not add manual servers locally; document the block and hand off to `@devops`.
+3.4. Add MCP server entries with proper structure to `.mcp.json` unless an existing managed policy dictates another surface:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "@package/mcp-server"],
+      "env": {
+        "API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+3.5. Preserve manual ownership rules:
+   - Manual MCP definitions suppress duplicate plugin servers
+   - Between plugins, first-loaded wins when signatures collide
+3.6. If writing `.mcp.json` outside Claude Code's native flow, use temp file -> flush -> atomic rename semantics.
+3.7. Validate JSON structure after writing.
+
+---
+
+## Phase 4: Transport Selection
+
+**Goal:** Choose the right transport protocol for each MCP server.
+
+### Transport Comparison
+
+| Transport | Protocol | Use Case | Latency | Setup |
+|-----------|----------|----------|---------|-------|
+| **stdio** (default) | local child process | Local CLI tools, most servers | Low | Simple |
+| **Remote HTTP** | streamable HTTP endpoint | Remote servers, shared infra | Medium | URL + auth |
+
+### Decision Tree
+
+```
+Is the MCP server running locally?
+  YES -> Use stdio (default)
+    Is it a CLI binary? -> command + args
+    Is it a Docker container? -> docker run command
+  NO -> Use remote HTTP
+    Does it need auth? -> Add Authorization header
+    Is it behind a proxy? -> Configure proxy URL
+```
+
+4.1. For each MCP server, determine if local or remote.
+4.2. Configure transport accordingly.
+4.3. Set environment variables for API keys (never hardcode in config).
+4.4. Record whether remote hosting, enterprise policy, or plugin ownership affects operability.
+
+---
+
+## Phase 5: Tool Validation
+
+**Goal:** Verify each MCP server is working and its tools are accessible.
+
+### Steps
+
+5.1. Start Claude Code with the new configuration.
+5.2. For each configured MCP server, verify tool availability:
+   - Check that tools appear in tool list
+   - Run a minimal test call (e.g., context7 resolve-library-id with "react")
+5.3. Document any servers that fail to connect.
+5.4. If a server fails, check:
+   - Binary installed? (command exists)
+   - API key valid? (env vars set)
+   - Port available? (for HTTP transport)
+   - Network accessible? (for remote servers)
+   - Duplicate manual/plugin definitions causing suppression?
+
+---
+
+## Phase 6: Documentation
+
+**Goal:** Update project documentation with MCP usage rules.
+
+### CLI-First vs MCP Decision Tree
+
+```
+Need to accomplish a task?
+  |
+  Can a native Claude Code tool do it?
+  (Read, Write, Edit, Bash, Grep, Glob)
+    YES -> Use native tool (ALWAYS prefer)
+    NO  -> Is there an MCP tool for it?
+      YES -> Use MCP tool
+      NO  -> Use Bash to install/run external tool
+```
+
+### Steps
+
+6.1. Add or update MCP section in CLAUDE.md with:
+   - List of configured servers and their purposes
+   - Tool selection priority (native > MCP > Bash)
+   - Server-specific usage rules and ownership notes
+6.2. Create `.claude/rules/mcp-usage.md` if it does not exist, with path-based activation.
+6.3. Document any server-specific gotchas (auth, rate limits, enterprise policy, plugin suppression, etc.).
+
+---
+
+## Output Format
+
+```yaml
+mcp_workflow_result:
+  servers_configured:
+    - name: "context7"
+      transport: "stdio"
+      tools: 2
+      token_cost: 500
+      status: "verified"
+    - name: "playwright"
+      transport: "stdio"
+      tools: 15
+      token_cost: 2450
+      status: "verified"
+  total_token_cost: 2950
+  budget_status: "green"
+  files_modified:
+    - ".mcp.json"
+    - ".claude/settings.json"
+    - "CLAUDE.md"
+  documentation_updated: true
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| MCP token budget exceeds 15,000 tokens | HALT -- must remove servers before proceeding |
+| API key required but not provided | SKIP server -- document as pending |
+| MCP server binary not installable | SKIP server -- suggest alternative |
+| Enterprise `managed-mcp.json` has exclusive control | HALT -- document policy owner and escalate |
+| Config file write fails | HALT -- check file permissions |
+| Secrets would need to be hardcoded into `.mcp.json` | HALT -- move secret to env or managed secret surface |
+| All MCP servers fail validation | HALT -- likely environment issue, debug first |

package/pro/squads/claude-code-mastery/tasks/multi-project-setup.md

@@ -0,0 +1,261 @@
+# Task: Multi-Project Claude Code Setup
+
+**Task ID:** CCM-PI-004
+**Version:** 1.0.0
+**Command:** `*multi-project-setup`
+**Owner:** Conduit (project-integrator)
+**Purpose:** Set up Claude Code for multiple related projects, configuring shared user settings, project-specific overrides, shared MCP servers, and cross-project rules.
+
+## Contrato SINKRA
+
+task: multi-project-setup
+atomic_layer: Atom
+executor: project-integrator
+Domain: Operational
+accountability_token: TK-CCM-ACC-001
+Input:
+- contexto do projeto
+- objetivo da task
+- artefatos de referência
+Output:
+- multi-project-setup-report
+- recomendação executável
+output_schema: multi-project-plan-yaml
+Pre-Conditions:
+- Contexto do projeto disponível e legível
+- Artefatos de referência acessíveis ao executor
+- Critério de sucesso entendido antes da execução
+Post-Conditions:
+- Output publicado em formato auditável
+- Próximo passo explícito ou handoff emitido
+- Decisões relevantes registradas no artefato final
+Performance:
+- Execução em uma sessão sem falha silenciosa
+- Thresholds e veto conditions respeitados
+- Resultado acionável para o próximo executor
+Completion Criteria:
+- All projects detected and mapped
+- Shared config generated without duplication
+- Project isolation verified per workspace
+
+---
+
+
+## Overview
+
+```
+  Multiple Projects
+       |
+       v
+  +-----------------------+
+  | 1. Analyze Project    |
+  |    Relationships      |
+  +-----------------------+
+       |
+       v
+  +-----------------------+
+  | 2. Configure Shared   |
+  |    User Settings      |
+  +-----------------------+
+       |
+       v
+  +-----------------------+
+  | 3. Create Per-Project |
+  |    Settings           |
+  +-----------------------+
+       |
+       v
+  +-----------------------+
+  | 4. Set Up Shared      |
+  |    MCP Servers        |
+  +-----------------------+
+       |
+       v
+  +-----------------------+
+  | 5. Configure Shared   |
+  |    Rules              |
+  +-----------------------+
+       |
+       v
+  +-----------------------+
+  | 6. Verify Cross-      |
+  |    Project Coherence  |
+  +-----------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| projects | object[] | User | Yes | Array of {path, name, type} for each project |
+| relationship | enum | User | Yes | `monorepo`, `polyrepo-shared-stack`, `polyrepo-independent`, `workspace` |
+| shared_tools | string[] | User | No | Tools used across all projects (e.g., "eslint", "jest", "docker") |
+
+---
+
+## Preconditions
+
+- All listed project directories exist and are accessible
+- User has write access to `~/.claude/` (user-level config)
+- Each project has been initialized with git
+
+---
+
+## Execution Phases
+
+### Phase 1: Analyze Project Relationships
+
+For each project, determine:
+
+1. **Language and framework**: detect from package.json, Cargo.toml, pyproject.toml, etc.
+2. **Shared dependencies**: which packages appear across projects
+3. **Shared patterns**: naming conventions, directory structure similarities
+4. **Communication patterns**: do projects import from each other (monorepo), share APIs (microservices), or operate independently
+5. **Git topology**: single repo with multiple packages vs separate repositories
+
+Build a relationship map:
+```
+Project A (Next.js frontend) --imports--> shared-lib
+Project B (Node.js API)      --imports--> shared-lib
+Project C (Python ML)        --independent--
+shared-lib (TypeScript)      --consumed-by--> A, B
+```
+
+### Phase 2: Configure Shared User Settings
+
+Create or update `~/.claude/settings.json`:
+
+1. **Global permissions**: commands safe across all projects
+   - `git status`, `git diff`, `git log`
+   - Language-agnostic linters and formatters
+2. **Global denies**: dangerous commands regardless of project
+   - `rm -rf /`, `sudo`, `DROP DATABASE`, `git push --force`
+3. **Global preferences**: settings that apply everywhere
+   - Output format preferences
+   - Default model configuration
+
+Create or update `~/.claude/CLAUDE.md` (user-level):
+- Developer identity and preferences
+- Cross-project conventions (commit style, PR format)
+- Keep under 50 lines -- project-specific content goes in project CLAUDE.md
+
+### Phase 3: Create Per-Project Settings
+
+For each project, generate `.claude/settings.json`:
+
+1. **Project-specific allows**: build/test/lint commands for that stack
+   - Frontend: `npm run dev`, `npm run build`, `npx next`
+   - Backend: `npm run start:dev`, `npm run migrate`
+   - Python: `python -m pytest`, `pip install`
+2. **Project-specific denies**: protect that project's critical paths
+3. **additionalDirectories**: if projects reference each other
+   ```json
+   {
+     "additionalDirectories": ["../shared-lib"]
+   }
+   ```
+4. **Project CLAUDE.md**: project-specific context, build commands, structure
+
+Ensure no conflicts between user-level and project-level settings.
+
+### Phase 4: Set Up Shared MCP Servers
+
+Configure MCP servers that serve multiple projects:
+
+1. **Identify shared needs**: which MCPs benefit all projects
+   - Context7: documentation lookup (universal)
+   - EXA: web search (universal)
+   - Database: shared if projects use same DB
+2. **Configure at user level**: add shared MCPs to `~/.claude/settings.json`
+3. **Configure project-specific MCPs**: in each project's settings
+4. **Avoid duplication**: same MCP should not be configured at both levels
+
+### Phase 5: Configure Shared Rules
+
+Create rules that apply across projects:
+
+1. **User-level rules** (`~/.claude/rules/`): team conventions
+   - Commit message format
+   - Code review checklist
+   - Documentation standards
+2. **Project-level rules** (`.claude/rules/`): project-specific
+   - Coding standards for that language/framework
+   - Testing requirements for that project
+   - Architecture constraints
+3. **Shared rule templates**: for consistency across new projects
+
+### Phase 6: Verify Cross-Project Coherence
+
+Run verification across all projects:
+
+1. **No conflicts**: user-level and project-level settings do not contradict
+2. **Complete coverage**: every project has CLAUDE.md + settings.json
+3. **MCP consistency**: shared MCPs accessible from all projects
+4. **Rule consistency**: no contradictory rules across projects
+5. **Path accuracy**: additionalDirectories point to valid paths
+
+---
+
+## Output Format
+
+```markdown
+## Multi-Project Setup Report
+
+**Projects:** {N} projects configured
+**Relationship:** {relationship}
+**Date:** {YYYY-MM-DD}
+
+### Project Map
+
+| Project | Type | Stack | MCP Servers | Rules |
+|---------|------|-------|-------------|-------|
+| {name} | {type} | {stack} | {N} | {N} |
+
+### Shared Configuration
+
+- User settings: ~/.claude/settings.json ({N} allows, {N} denies)
+- User CLAUDE.md: ~/.claude/CLAUDE.md ({N} lines)
+- Shared MCPs: {list}
+- Shared rules: {list}
+
+### Per-Project Configuration
+
+**{project_name}:**
+- .claude/CLAUDE.md: {N} lines
+- .claude/settings.json: {N} allows, {N} denies
+- .claude/rules/: {N} files
+- additionalDirectories: {list or "none"}
+
+### Cross-Project Verification
+
+| Check | Status |
+|-------|--------|
+| No setting conflicts | PASS/FAIL |
+| All projects configured | PASS/FAIL |
+| MCP consistency | PASS/FAIL |
+| Rule consistency | PASS/FAIL |
+| Path accuracy | PASS/FAIL |
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** overwrite existing user-level settings without confirmation
+- **NEVER** add project paths to additionalDirectories without verifying they exist
+- **NEVER** configure MCP servers that require credentials without user providing them
+- **NEVER** modify settings of projects not listed in the input
+
+---
+
+## Completion Criteria
+
+- [ ] Project relationships analyzed and mapped
+- [ ] Shared user settings configured at ~/.claude/
+- [ ] Per-project settings created for each project
+- [ ] Shared MCP servers configured without duplication
+- [ ] Cross-project rules established
+- [ ] Coherence verification passed
+- [ ] Setup report delivered