Integracoes

Translation note: Originally authored in Portuguese (pt-BR) by Igor Uehara (igoruehara/spec-driven, MIT). Translated to English by this hub to keep the repository language consistent. Original content unchanged in meaning; see the upstream repo for the pt-BR source.

Skill: Team integrations and MCPs

This skill is orthogonal to the kickoff — you don't always know the tooling when starting the project. Run it when you do. It is idempotent: re-running updates docs/engineering/integrations.md.

When to run:

• Before /kickoff (ideal): the read MCPs feed vision/assessment/context-map with real data (read-first).
• After, at any time: when the tooling became known, or to set up writing. If the kickoff already ran and you pull new inputs here, offer to enrich the existing artifacts (context-map, glossary, assessment), citing the source.

Principles

• Connection lock (MCP): an already-active connection does not authorize use. Always confirm which account/workspace it points to before reading — and reconfirm before any write. Using the wrong account (e.g.: personal Notion instead of business) reads the wrong context and, on write, leaks project data outside the work context.
• Outward-facing actions (connect, publish, create issue) → confirm first.
• Tools-aware: only use an MCP available in the session (mcp__<server>__*); otherwise, document it and proceed.

Phase 1 — Survey the team's tools

Batches of AskUserQuestion:

• Management and process: Jira / Trello / Linear / Azure DevOps (+ Scrum / Kanban / Waterfall).
• Documentation: Confluence / Notion / Evernote / Google Docs.
• Code and CI: GitHub / GitLab / Bitbucket. Cloud: AWS / GCP / Azure.
• Observability and communication: Datadog / Sentry / Grafana; Slack / Teams.
• Libs/APIs: Context7 (lookup in the knowledge verification of CLAUDE.md).

Phase 2 — Read connection (read-first) + safety lock

For the read tools (Confluence, Jira, Notion, GitHub, cloud), check whether the MCP is already available in the session (mcp__<server>__*):

• Already connected → ⚠️ safety lock, do NOT use directly. It may point to the wrong account.
  1. Identify the account/workspace (if the MCP exposes it — e.g.: fetch the current workspace/user) and show it to the user. If it can't be verified, treat it as unconfirmed.
  2. Ask (AskUserQuestion): use this connection (workspace X) · reconnect / switch account (personal → business) · use another tool · skip this source.
  3. Only proceed after explicit confirmation. Record the account/workspace in integrations.md.
• Not connected → ask whether to connect. ⚠️ Adding a new MCP (.mcp.json / claude mcp add) usually only takes effect after reconnecting the session. Offer:
  • (a) connect now → reopen the session → run /integracoes (or /kickoff) again; or
  • (b) proceed without connecting → becomes an adoption roadmap item. Document in integrations.md.

Pull the available inputs (only from already-connected and validated MCPs) and cite the source (link/ID):

• Confluence / Notion: business decisions, vision, domain, architecture.
• Jira / Linear: epics, current roadmap, open stories.
• GitHub / cloud: code and infra context (as-is).

Phase 3 — Write plan (write-side)

1. Map each tool to the MCP server (table in docs/engineering/_templates/integrations.template.md). Verify the name/availability in the official docs — do not invent package names.
2. Define the write flows and when they fire — rule: read early, write at the gate:
   • "Approved" gate of vision/design/spec/roadmap → publish to Confluence/Notion.
   • Breakdown of tasks.md → create issues/subtasks in Jira/Linear.
   • New ADR → comment on the GitHub/GitLab PR. Event (approved/merged) → Slack/Teams.
   • Writing is always repo → tool (one way); store the back-reference key (jira:, confluence:).
   • ⚠️ Before the first write, reconfirm the destination account/workspace (same lock).
3. Scaffolding (confirm first). If approved, generate .mcp.json at the root with placeholders, no secrets (tokens via env / claude mcp add). Do not commit credentials.

Phase 4 — Generate/update docs/engineering/integrations.md

From docs/engineering/_templates/integrations.template.md: tools, MCPs, validated account/workspace, read/write flows, and status. If the kickoff already ran and you pulled new inputs, offer to enrich context-map.md / glossary.md / assessment.md with what you found (citing the source).

Phase 5 — Register in the routing (rules + skills)

A validated connection is not enough: the rest of the pipeline needs to know it exists and who uses it.

1. CLAUDE.md (rules): update the "Connected tools (MCP)" block with the validated servers — mcp__<server>__*, account/workspace, and which skills consume each one. Since CLAUDE.md is alwaysApply: true, every session now carries this routing.
2. Skills (routing): confirm that the tools-aware skills point to the right MCPs — /nova-feature (Jira/Linear/Confluence/Notion), /revisar-pr (GitHub/GitLab), /publicar-* (Confluence/Notion). Do not duplicate logic: the skills check mcp__<server>__* at runtime.
3. Agentic layer: if the new tools call for new artifacts (/spec-to-jira skill, subagent, publish hook), delegate to /camada-agentica (proposes with justification, generates only what is approved). Unapproved items become adoption roadmap items.

Closing

• Summarize with clickable links and list the MCPs that entered the routing (CLAUDE.md).
• Next step: if /kickoff hasn't run yet, suggest running it now (with the read MCPs already connected, the artifacts come out with real data). Otherwise, point to /nova-feature. If you registered new tools, consider /camada-agentica to tune the pipeline to them.