iron-edge 1.0.0

package/squads/squad-claude/tasks/integrate-project.md

@@ -0,0 +1,73 @@
+---
+task: integrate-project
+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"
+---
+
+# Integrate Project
+
+## Objective
+
+Integrate Claude Code into an existing project by assessing current state, identifying the optimal configuration for the project's stack, and creating all necessary configuration files without disrupting existing workflows.
+
+## Inputs
+
+- Project root path
+- Technology stack (language, framework, package manager)
+- Existing AI tooling (Copilot, Cursor, other)
+- Team conventions and coding standards
+- CI/CD pipeline (if any)
+
+## Steps
+
+1. **Scan Project Structure** — Map the repository: identify source directories, test directories, config files, build systems, and any existing .claude/ or CLAUDE.md files.
+2. **Identify Framework** — Detect the primary framework(s): Next.js, React, Vue, Angular, Express, FastAPI, Django, Rust, Go, etc. Each has specific Claude Code optimization patterns.
+3. **Assess Current AI Tooling** — Check for existing AI configurations (.cursor/, .github/copilot/, etc.). Plan how Claude Code will coexist or replace these.
+4. **Generate CLAUDE.md** — Delegate to `@config-engineer` via `claude-md-engineer` task. Include framework-specific conventions, project structure, and coding standards.
+5. **Configure Settings** — Delegate to `@config-engineer` via `configure-settings` task. Set permissions appropriate for the project's security requirements.
+6. **Create Initial Rules** — Delegate to `@config-engineer` via `create-rules` task. Create rules for the most common file patterns in the project.
+7. **Validate Integration** — Run a test session: read a file, make a small edit, run a command. Verify Claude Code behaves according to the configuration.
+8. **Document Integration** — Produce a summary of what was configured, what conventions were adopted, and what the team needs to know.
+
+## Quality Gates
+
+- All config files must pass validation
+- CLAUDE.md must reference actual project paths and conventions
+- No existing workflows disrupted (existing tooling still works)
+- Test session must complete without permission errors or misconfigurations
+
+## Output Format
+
+```markdown
+# Project Integration Complete
+
+## Project: {name}
+## Stack: {stack}
+
+## Files Created
+- {list}
+
+## Configuration Summary
+- Permissions: {mode}
+- Rules: {count} files
+- MCP servers: {count}
+
+## Team Onboarding Notes
+{what the team needs to know}
+```

package/squads/squad-claude/tasks/knowledge-base-architecture.md

@@ -0,0 +1,107 @@
+---
+task: knowledge-base-architecture
+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"
+---
+
+# Knowledge Base Architecture
+
+## Objective
+
+Design a knowledge base architecture for AI-assisted projects that organizes reference material, patterns, and domain knowledge into an efficient, searchable, and maintainable structure. Ensure knowledge is accessible to AI agents at the right time with minimal context window overhead.
+
+## Pre-Conditions
+
+- Knowledge domains and categories identified for the project
+- Content sources available (documentation, code patterns, decision records, guides)
+- Token budget constraints defined per knowledge category
+- Claude Code rules system understood (for integration with retrieval)
+- Maintenance ownership and update cadence established
+
+## Steps
+
+1. **Audit Existing Knowledge** — Inventory all existing knowledge scattered across the project: README files, inline comments, wiki pages, Slack messages, code patterns, architectural decisions, and tribal knowledge. Estimate the total volume and identify gaps.
+2. **Define Knowledge Taxonomy** — Create a hierarchical taxonomy: top-level domains (architecture, patterns, tools, processes), mid-level categories (per domain), and leaf-level topics (specific knowledge items). Each node should have a clear scope statement.
+3. **Design File Structure** — Map the taxonomy to a file structure: one file per major category, consistent naming convention (kebab-case, descriptive names), clear directory hierarchy, and index files for navigation. Balance between too many small files (hard to find) and too few large files (wasteful token loading).
+4. **Create Content Templates** — Design templates for each knowledge type: reference guides (structured tables, concise explanations), pattern libraries (name, context, solution, example), decision records (context, decision, consequences), and how-to guides (steps with examples).
+5. **Write Content Guidelines** — Establish quality standards for KB entries: write for AI consumption (structured, scannable, no fluff), include concrete examples, use tables over paragraphs, keep entries self-contained (no cross-file dependencies for understanding), and version each entry.
+6. **Design Search and Retrieval** — Create retrieval mechanisms: consistent headers and tags for grep-based search, file naming that enables glob-based discovery, integration with Claude Code rules system (path-conditional loading), and a KB index file listing all entries with descriptions.
+7. **Implement Tiered Loading** — Classify KB content into loading tiers: always-loaded (critical conventions, under 1000 tokens), path-conditional (loaded when working on related files), and on-demand (searched and loaded when needed). Minimize always-loaded content.
+8. **Build Maintenance Workflow** — Define how the KB stays current: who owns each section, review schedule (monthly for active areas, quarterly for stable), contribution process (how to add new entries), deprecation process (how to retire outdated entries), and quality review checklist.
+9. **Create Cross-Reference System** — Design how KB entries reference each other: use consistent link format, maintain a dependency graph (which entries reference which), and detect broken references automatically. Avoid circular dependencies.
+10. **Validate Architecture** — Test the KB architecture: can an AI agent find the right knowledge for 10 sample questions? Is the token overhead acceptable? Are there gaps in coverage? Is the structure intuitive for new contributors?
+
+## Output
+
+```markdown
+# Knowledge Base Architecture
+
+## Taxonomy
+```
+knowledge-base/
+├── {domain-1}/
+│   ├── {category-1}.md
+│   └── {category-2}.md
+├── {domain-2}/
+│   ├── {category-1}.md
+│   └── {category-2}.md
+└── KB-INDEX.md
+```
+
+## Content Templates
+### Reference Guide Template
+{template}
+
+### Pattern Library Template
+{template}
+
+### Decision Record Template
+{template}
+
+## Loading Tiers
+| Tier | Content | Token Budget | Loading Method |
+|------|---------|-------------|---------------|
+
+## Maintenance Schedule
+| Section | Owner | Review Cycle | Last Reviewed |
+|---------|-------|-------------|--------------|
+
+## Search Guide
+| Query Type | Method | Example |
+|-----------|--------|---------|
+| Find by topic | Grep header | `grep "## {topic}"` |
+| Find by tag | Grep tag | `grep "tags:.*{tag}"` |
+| Browse domain | Glob | `ls knowledge-base/{domain}/` |
+
+## Quality Metrics
+| Metric | Target | Current |
+|--------|--------|---------|
+| Coverage (domains with KB) | 100% | {%} |
+| Freshness (entries updated < 90d) | 80% | {%} |
+| Token efficiency (useful/total) | > 70% | {%} |
+```
+
+## Quality Criteria
+
+- Taxonomy must cover all identified knowledge domains with no orphan entries
+- Always-loaded content must total under 1000 tokens
+- Every KB entry must follow the appropriate content template
+- Search must return relevant results for 90% of test queries within 2 attempts
+- Maintenance workflow must have clear ownership for every section
+- Architecture must be extensible (adding a new domain requires no structural changes)

package/squads/squad-claude/tasks/knowledge-retrieval-optimization.md

@@ -0,0 +1,90 @@
+---
+task: knowledge-retrieval-optimization
+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"
+---
+
+# Knowledge Retrieval Optimization
+
+## Objective
+
+Optimize knowledge retrieval patterns for Claude Code projects so that the right information is available at the right time without wasting context tokens on irrelevant content. Design tiered retrieval strategies that balance immediacy with token efficiency.
+
+## Pre-Conditions
+
+- Knowledge base files exist (KBs, docs, reference material)
+- Usage patterns observed (which knowledge is accessed when)
+- Context window budget constraints established
+- Claude Code rules system understood (paths: frontmatter, directory CLAUDE.md)
+- Project workflow stages documented
+
+## Steps
+
+1. **Catalog Knowledge Assets** — Inventory all knowledge sources: KB files, documentation, reference tables, code examples, API specs, and decision records. For each, record: token count, access frequency, usage context (which tasks need it), and staleness risk.
+2. **Analyze Access Patterns** — Map which knowledge is needed for which tasks: development tasks need API specs and code patterns, review tasks need quality criteria, setup tasks need configuration references. Create a task-to-knowledge dependency matrix.
+3. **Design Retrieval Tiers** — Create a tiered retrieval system: Tier 1 (always in context) — critical rules and conventions, < 2000 tokens; Tier 2 (loaded by path trigger) — file-specific knowledge, loaded via rules with `paths:` frontmatter; Tier 3 (on-demand) — searchable reference material, retrieved via Grep when needed.
+4. **Optimize Tier 1 Content** — Review always-loaded content ruthlessly: every token must earn its place. Compress tables, remove explanatory prose Claude already understands, use shorthand notation, and link to Tier 2/3 for details instead of including them.
+5. **Configure Tier 2 Triggers** — For each piece of path-conditional knowledge, define the optimal trigger pattern: which file paths should load this knowledge? Too broad = wasted tokens, too narrow = knowledge missing when needed. Test trigger patterns against real workflow scenarios.
+6. **Build Tier 3 Search Index** — Organize on-demand knowledge for efficient retrieval: use consistent file naming, add searchable headers and tags, structure content with clear sections that can be extracted independently, and create a search guide documenting what is available and where.
+7. **Implement Preloading Heuristics** — Design rules that preload knowledge based on context signals: if the user mentions "database", preload schema reference; if working on tests, preload test patterns; if in a specific directory, preload that component's documentation.
+8. **Create Knowledge Freshness Protocol** — Define how knowledge stays current: review schedule per knowledge category, staleness indicators (references to deprecated APIs, old file paths), automated freshness checks (grep for referenced paths that no longer exist), and update workflow.
+9. **Measure Retrieval Effectiveness** — Design metrics to evaluate the retrieval system: hit rate (was the right knowledge available when needed?), waste rate (was irrelevant knowledge loaded?), miss rate (was needed knowledge not available?), and latency (how quickly was knowledge retrieved?).
+10. **Document Retrieval Architecture** — Create a complete document showing: the tiered system, how to add new knowledge, how to configure triggers, how to search, and how to maintain the system.
+
+## Output
+
+```markdown
+# Knowledge Retrieval Optimization
+
+## Knowledge Inventory
+| Asset | Tokens | Tier | Trigger | Access Frequency |
+|-------|--------|------|---------|-----------------|
+
+## Tier Architecture
+| Tier | Strategy | Budget | Content Types |
+|------|----------|--------|--------------|
+| 1 | Always loaded | {tokens} | {types} |
+| 2 | Path-conditional | {tokens max} | {types} |
+| 3 | On-demand search | unlimited | {types} |
+
+## Tier 2 Trigger Map
+| Knowledge File | Path Pattern | Estimated Loads/Day |
+|---------------|-------------|-------------------|
+
+## Preloading Heuristics
+| Context Signal | Knowledge Preloaded | Trigger Method |
+|---------------|-------------------|---------------|
+
+## Freshness Protocol
+| Category | Review Cycle | Staleness Check | Owner |
+|----------|-------------|----------------|-------|
+
+## Effectiveness Metrics
+| Metric | Target | Measurement Method |
+|--------|--------|-------------------|
+```
+
+## Quality Criteria
+
+- Tier 1 content must be under 2000 tokens total
+- Tier 2 triggers must have zero false-negative rate (never miss loading needed knowledge)
+- Tier 3 search must return relevant results within 2 search queries
+- Overall retrieval system must reduce token waste by at least 25% vs. flat loading
+- Freshness protocol must catch stale references within one review cycle
+- Documentation must enable a new team member to understand and extend the system

package/squads/squad-claude/tasks/mcp-integration-audit.md

@@ -0,0 +1,98 @@
+---
+task: mcp-integration-audit
+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"
+---
+
+# MCP Integration Audit
+
+## Objective
+
+Audit all existing MCP server integrations in a project for health, security, performance, and usage patterns. Identify unused servers, misconfigured tools, security vulnerabilities, and optimization opportunities. Produce an actionable audit report with prioritized remediation steps.
+
+## Pre-Conditions
+
+- Access to project MCP configuration (settings.json, .claude.json, Docker MCP config)
+- List of all configured MCP servers and their purposes
+- Access to run diagnostic commands against each server
+- Understanding of which tools are actively used vs. dormant
+- Security policy for credential management
+
+## Steps
+
+1. **Inventory All MCP Servers** — Scan all configuration sources: project settings.json, user .claude.json, Docker MCP catalog, and any custom server registrations. List every server with its name, transport type, tool count, and configuration status.
+2. **Test Connectivity** — For each server, perform a health check: attempt connection, verify handshake, list available tools, and measure connection latency. Flag servers that fail to connect or have latency above 5 seconds.
+3. **Audit Security Configuration** — For each server, check: are credentials stored in environment variables (not hardcoded)? Are API keys rotated regularly? Is network access scoped appropriately? Are tool permissions restrictive or permissive? Flag any security violations.
+4. **Analyze Usage Patterns** — Review recent usage data: which tools are called frequently, which are never used, which have high error rates. Cross-reference with project needs to identify servers that are no longer needed.
+5. **Check for Redundancy** — Identify overlapping capabilities: multiple servers providing similar tools (e.g., two web search servers), tools duplicating native Claude Code capabilities, or servers with overlapping resource access.
+6. **Assess Performance Impact** — Measure the performance overhead of each server: startup time, per-tool latency, memory usage, and impact on Claude Code context window (tool descriptions consume tokens). Calculate total MCP overhead.
+7. **Verify Error Handling** — For each server, trigger common error scenarios: invalid input, auth failure, timeout. Verify that error messages are informative, non-leaking (no credentials in errors), and that failures don't crash the Claude Code session.
+8. **Review Configuration Drift** — Compare current configuration against the documented integration plan (if one exists). Identify configuration that has drifted: changed environment variables, updated server versions, added/removed tools without documentation.
+9. **Generate Remediation Plan** — Prioritize findings by severity (Critical/High/Medium/Low). For each finding, provide: description, impact, remediation steps, estimated effort, and responsible party. Group related findings.
+10. **Produce Audit Report** — Compile all findings into a structured report with executive summary, detailed findings, server-by-server health cards, and the prioritized remediation plan.
+
+## Output
+
+```markdown
+# MCP Integration Audit Report
+
+## Executive Summary
+- Servers audited: {count}
+- Healthy: {count} | Degraded: {count} | Failed: {count}
+- Critical findings: {count}
+- Estimated remediation effort: {hours}
+
+## Server Health Cards
+### {Server Name}
+| Metric | Value | Status |
+|--------|-------|--------|
+| Connectivity | {pass/fail} | {emoji} |
+| Security | {score}/5 | {emoji} |
+| Usage (30d) | {call count} | {active/dormant} |
+| Latency (p95) | {ms} | {ok/slow} |
+| Error rate | {%} | {ok/high} |
+
+## Findings
+| # | Severity | Server | Finding | Remediation |
+|---|----------|--------|---------|-------------|
+
+## Remediation Plan
+### Critical (fix immediately)
+1. {finding + steps}
+
+### High (fix this sprint)
+1. {finding + steps}
+
+### Medium (schedule)
+1. {finding + steps}
+
+## Recommendations
+- Remove: {servers to decommission}
+- Upgrade: {servers needing updates}
+- Add: {missing capabilities}
+```
+
+## Quality Criteria
+
+- Every configured MCP server must be tested (zero skipped)
+- Security audit must check credentials storage, network scope, and permission breadth
+- Usage analysis must cover at least 30 days of activity (or available history)
+- Remediation plan must have estimated effort for every Critical and High finding
+- Audit report must be actionable without requiring additional investigation
+- Redundant servers must be identified with a specific recommendation (keep/remove/merge)

package/squads/squad-claude/tasks/mcp-integration-plan.md

@@ -0,0 +1,75 @@
+---
+task: mcp-integration-plan
+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"
+---
+
+# MCP Integration Plan
+
+## Objective
+
+Design a comprehensive MCP integration plan for a project, selecting the right servers, transport types, and security configurations. Produce ready-to-use configuration entries for settings.json.
+
+## Inputs
+
+- Project requirements (what external services are needed)
+- Available MCP servers (from marketplace or custom)
+- Infrastructure constraints (Docker available? Network restrictions?)
+- Security requirements (authentication, network isolation)
+- Budget for external services
+
+## Steps
+
+1. **Inventory Requirements** — List all external service integrations needed: database (Supabase), version control (GitHub), design (Figma), communication (Slack, Gmail), documentation (Notion), etc.
+2. **Match Servers to Requirements** — For each requirement, identify the best MCP server. Check official registry, community servers, and evaluate if a custom server is needed.
+3. **Select Transport Types** — For each server, choose transport: stdio for local CLI tools, SSE for remote HTTP services, Docker for isolated/managed deployments. Document the rationale.
+4. **Design Security Configuration** — For each server: define required environment variables, authentication method, network access scope, and tool-level permissions.
+5. **Plan Installation Order** — Sequence server installations to handle dependencies. Some servers may depend on others being available first.
+6. **Generate Configuration** — Produce the complete MCP server configuration block for settings.json with all servers, their transports, commands, args, and env references.
+7. **Create Test Plan** — For each server, define a smoke test: connect, list tools, execute one representative tool call, verify response.
+
+## Quality Gates
+
+- Every requirement must map to at least one MCP server
+- No server should have hardcoded credentials (environment variables only)
+- Transport type must match infrastructure constraints
+- Each server must have a documented smoke test
+- Total number of MCP servers should not exceed reasonable limits (< 15 for performance)
+
+## Output Format
+
+```markdown
+# MCP Integration Plan
+
+## Server Registry
+| # | Server | Transport | Purpose | Auth Method |
+|---|--------|-----------|---------|-------------|
+
+## Configuration (settings.json)
+{JSON block}
+
+## Environment Variables Required
+{list with descriptions}
+
+## Smoke Tests
+{per-server test instructions}
+
+## Installation Order
+1. ...
+```

package/squads/squad-claude/tasks/mcp-server-design.md

@@ -0,0 +1,94 @@
+---
+task: mcp-server-design
+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"
+---
+
+# MCP Server Design
+
+## Objective
+
+Design a custom MCP (Model Context Protocol) server architecture from scratch, including tool definitions, resource endpoints, transport configuration, authentication, error handling, and deployment strategy. Produce a complete technical specification ready for implementation.
+
+## Pre-Conditions
+
+- Use case requiring custom MCP server identified (no existing server covers the need)
+- Target API or service to wrap is documented and accessible
+- MCP SDK version and transport requirements known (stdio, SSE, streamable HTTP)
+- Security and authentication requirements defined
+- Performance requirements established (latency, throughput, concurrent connections)
+
+## Steps
+
+1. **Define Server Scope** — Document exactly what the MCP server will expose: list of tools (actions the model can take), list of resources (data the model can read), and list of prompts (templates the model can use). Each must have a clear purpose statement.
+2. **Design Tool Schemas** — For each tool, define: name (verb-noun format), description (what it does and when to use it), input schema (JSON Schema with required/optional fields, types, validation), and output schema (response structure with examples).
+3. **Design Resource Endpoints** — For each resource, define: URI pattern, MIME type, description, and access pattern (direct read, template with parameters, subscription for updates). Include pagination strategy for large resources.
+4. **Plan Transport Layer** — Select and configure the transport: stdio for CLI integration, SSE for HTTP streaming, or streamable HTTP for modern deployments. Define connection lifecycle, reconnection strategy, and timeout configuration.
+5. **Architect Authentication** — Design the auth flow: API key injection via environment variables, OAuth2 token management, or custom auth headers. Define how credentials are stored (never hardcoded), rotated, and validated on each request.
+6. **Design Error Handling** — Create an error taxonomy: auth failures (401/403), rate limits (429), service unavailable (503), invalid input (400), and internal errors (500). For each, define the MCP error response format and recovery suggestion.
+7. **Plan Rate Limiting and Caching** — Design rate limit handling: detect limits from upstream API, implement backoff strategy, queue requests when throttled. Design caching layer for repeated reads: TTL per resource type, cache invalidation triggers.
+8. **Write Server Configuration Schema** — Define the configuration file format: server name, version, transport settings, auth configuration, tool toggles (enable/disable individual tools), logging level, and custom options.
+9. **Design Logging and Observability** — Plan structured logging: request/response logging (with PII redaction), performance metrics (latency per tool), error rates, and health check endpoint. Define log levels and rotation policy.
+10. **Create Deployment Specification** — Document deployment options: npm package (for stdio), Docker container (for isolated deployment), or cloud function (for serverless). Include Dockerfile, package.json scripts, and CI/CD pipeline requirements.
+11. **Write Integration Test Plan** — Define integration tests: connect to server, list tools/resources, execute each tool with valid input, execute with invalid input, test auth failure, test rate limit handling, test concurrent requests.
+
+## Output
+
+```markdown
+# MCP Server Design: {Server Name}
+
+## Overview
+- Purpose: {what this server enables}
+- Transport: {stdio | SSE | streamable HTTP}
+- Tools: {count}
+- Resources: {count}
+
+## Tool Definitions
+### {tool_name}
+- Description: {description}
+- Input Schema: {JSON Schema}
+- Output Schema: {JSON Schema}
+- Error Cases: {list}
+
+## Resource Definitions
+### {resource_uri}
+- MIME Type: {type}
+- Access Pattern: {direct | template | subscription}
+
+## Configuration Schema
+{JSON Schema for server config}
+
+## Deployment
+- Primary: {deployment method}
+- Dockerfile: {included}
+- CI/CD: {pipeline spec}
+
+## Integration Tests
+| Test | Tool/Resource | Input | Expected | Priority |
+|------|--------------|-------|----------|----------|
+```
+
+## Quality Criteria
+
+- Every tool must have a complete JSON Schema for input and output
+- Error handling must cover all 5 error categories with specific recovery suggestions
+- Authentication must never expose credentials in logs or error messages
+- Server must handle graceful shutdown (complete in-flight requests before exit)
+- Design must include at least one caching strategy for read-heavy tools
+- Deployment spec must include health check endpoint and readiness probe

package/squads/squad-claude/tasks/mcp-workflow.md

@@ -0,0 +1,75 @@
+---
+task: mcp-workflow
+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"
+---
+
+# MCP Workflow
+
+## Objective
+
+Create MCP-powered workflows that combine multiple MCP servers into coherent automation pipelines. Design tool chains where the output of one MCP tool feeds into another, enabling complex cross-service automations.
+
+## Inputs
+
+- Workflow goal (e.g., "sync Figma designs to code", "auto-create GitHub issues from Notion tasks")
+- Available MCP servers (already configured)
+- Trigger condition (manual, hook-based, scheduled)
+- Data flow requirements (what data moves between services)
+
+## Steps
+
+1. **Map Data Flow** — Draw the data flow between MCP servers: Source -> Transform -> Destination. Identify what data each tool needs and produces.
+2. **Identify Tool Chain** — For each step in the flow, identify the specific MCP tool to call. Verify each tool's input/output schema is compatible with the chain.
+3. **Design Error Handling** — For each step: what happens on failure? Retry? Skip? Compensate (undo previous steps)? Alert?
+4. **Handle Authentication Flow** — Ensure each server in the chain has valid credentials and that token refresh or re-authentication is handled gracefully.
+5. **Build Orchestration Logic** — Write the orchestration as either a hook chain (for event-driven), a Claude Code skill (for manual trigger), or a CI/CD step (for scheduled).
+6. **Add Monitoring** — Design health checks and logging for each step in the workflow. Include latency tracking and error rate monitoring.
+7. **Test End-to-End** — Create a test scenario that exercises the full workflow with representative data.
+
+## Quality Gates
+
+- Data flow must be fully mapped with no gaps
+- Every tool in the chain must have compatible input/output schemas
+- Error handling must cover all failure modes
+- Authentication must not require manual intervention during workflow execution
+- End-to-end test must pass
+
+## Output Format
+
+```markdown
+# MCP Workflow: {name}
+
+## Data Flow Diagram
+{ASCII diagram or description}
+
+## Tool Chain
+| Step | MCP Server | Tool | Input | Output |
+|------|-----------|------|-------|--------|
+
+## Error Handling Matrix
+| Step | Failure Mode | Action |
+|------|-------------|--------|
+
+## Orchestration
+{hook config / skill definition / CI step}
+
+## Test Plan
+{end-to-end test scenario}
+```