From 0b88d5c47e520f6254ed44741fce3457232ca721 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 12:53:35 +0800 Subject: [PATCH 01/16] docs(aidd-context): clarify service connections by category --- .../assets/recipes/mcp-installation.md | 181 +++++++----------- 1 file changed, 65 insertions(+), 116 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index 67b564bee..c7ccfd86f 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -1,156 +1,105 @@ -# MCP installations +# Connect your services -Choose between a CLI and MCP by capability, then install the integration through the configuration native to your AI client. +Choose a CLI or MCP server so your AI assistant can work with your team's services. - + -## Steps to install the right integration +## Steps to connect your services -### 1) πŸ”Ž Choose by capability +### 1) πŸ”Ž Choose the tool -Choose the smallest interface that fully covers the workflow, authentication model, and data scope. +Start with the CLI when it covers your task and your assistant can run shell commands. Use MCP when you need its tools inside the assistant. -1. Compare the exact operation you need against the table. +Memory links open the AIDD templates for the corresponding files in your project's `aidd_docs/memory/`. -| Need | Prefer a CLI | Prefer MCP | -| --- | --- | --- | -| Scriptable commands and raw API calls | The official CLI covers the operation and its output is manageable | The client needs typed discovery or structured results | -| Live design or knowledge context | The CLI exposes the required operation and data | The server advertises the required tools, resources, or prompts | -| Authentication | The CLI's login and credential storage fit the workflow | The server's authentication, requested scopes, and host credential storage fit the workflow | -| Context cost | Output is requested only when the command runs | The client supports deferred loading such as [Claude Code Tool Search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) | +**Version control** -The last column is a decision heuristic for this recipe, not a provider guarantee. +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| GitHub | Issues, PRs, releases, CI runs | CLI: [`gh`](https://cli.github.com/manual/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | +| GitLab | Issues, merge requests, pipelines | CLI: [`glab`](https://docs.gitlab.com/cli/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | -β€œOfficial” means published by the service provider, not a guarantee of production readiness or contractual support. Statuses below were checked against the linked provider sources on 2026-10-13. β€œNot listed” means this recipe does not identify an official option. +**Ticketing** -| Usage | Service | MCP offered and status | CLI alternative and status | Recommended | -| --- | --- | --- | --- | --- | -| **Version control**: Manage issues, PRs, releases, and CI runs | **GitHub** | **Official**: [`api.githubcopilot.com/mcp/`](https://github.com/github/github-mcp-server) | **Official**: [`gh`](https://cli.github.com/manual/) | **CLI** | -| - | **GitLab** | **Official, experimental**: [`glab mcp serve`](https://docs.gitlab.com/cli/mcp/) | **Official**: [`glab`](https://docs.gitlab.com/cli/) | **CLI** | -| **Ticketing**: Search, create, and update tickets | **Jira** | **Official**: [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | **Official**: [`acli`](https://developer.atlassian.com/cloud/acli/guides/introduction/) | **CLI** | -| - | **Linear** | **Official**: [`mcp.linear.app/mcp`](https://linear.app/docs/mcp) | Not listed | **MCP** | -| **Internal Doc**: Search and maintain team documentation | **Confluence** | **Official**: [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | Not listed | **MCP** | -| - | **Notion** | **Official**: [`mcp.notion.com/mcp`](https://developers.notion.com/guides/mcp/get-started-with-mcp) | **Official**: [`ntn`](https://developers.notion.com/cli/get-started/overview) for API and page operations | **CLI** for scripts and API work; **MCP** for agent workflows | -| **Workspace**: Work with Drive, Docs, Sheets, Gmail, and Calendar | **Google Workspace** | Not listed | [`gws`](https://github.com/googleworkspace/cli): published under `googleworkspace`, but **not officially supported by Google** | **CLI**, if its support status meets the project's requirements | -| **Browsing**: Test user journeys and inspect browser behavior | **Playwright** | **Official**: [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) | **Official**: [`playwright-cli`](https://playwright.dev/agent-cli/installation) for browser automation; [`npx playwright`](https://playwright.dev/docs/test-cli) for tests | **CLI** for direct browser automation and tests; **MCP** for live tool calls | -| **UI**: Read design context to implement an interface | **Figma** | **Official**: [`mcp.figma.com/mcp`](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | **Official**: [`@figma/code-connect`](https://developers.figma.com/docs/code-connect/cli-reference/) for component mappings, not live design context | **CLI** for Code Connect mappings; **MCP** for live design context | -| **Monitoring**: Inspect errors and investigate incidents | **Sentry** | **Official**: [`mcp.sentry.dev/mcp`](https://github.com/getsentry/toolkit) | **Official**: [`sentry`](https://cli.sentry.dev/) for issue investigation; [`sentry-cli`](https://github.com/getsentry/sentry-cli) for releases and source maps | **CLI** when it covers the investigation; **MCP** for interactive debugging | -| **Deployment**: Deploy applications and inspect deployment logs | **Vercel** | **Official**: [`mcp.vercel.com`](https://vercel.com/docs/agent-resources/vercel-mcp) | **Official**: [`vercel`](https://vercel.com/docs/cli) | **CLI** for repeatable deployment workflows; **MCP** for interactive exploration | -| **Database**: Manage migrations, develop locally, and explore a project | **Supabase** | **Official**: [`mcp.supabase.com/mcp`](https://supabase.com/docs/guides/ai-tools/mcp) | **Official**: [`supabase`](https://supabase.com/docs/reference/cli/introduction) | **CLI** for migrations and local development; **MCP** for interactive exploration | +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Jira Cloud | Search, create, update tickets | CLI: [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | +| Linear | Search, create, update tickets | [Linear MCP](https://linear.app/docs/mcp) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | -### 2) ⌨️ Install the CLI route +**Documentation and workspace** -The agent-oriented Playwright CLI is a direct browser alternative to Playwright MCP. +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Confluence | Search and edit team documentation | [Atlassian MCP](https://www.atlassian.com/platform/rovo-mcp) | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | +| Notion | Search and edit workspace pages | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp); CLI: [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | +| Google Workspace | Drive, Docs, Sheets, Gmail, Calendar | CLI: [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | -1. Install `@playwright/cli` from the [official guide](https://playwright.dev/agent-cli/installation), then invoke its `playwright-cli` executable. +**Browser** -```bash -npm install -g @playwright/cli@latest -playwright-cli open https://example.com --headed -``` - -Optional rollback: `npm uninstall -g @playwright/cli`. +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Playwright | Browse and inspect a website | CLI: [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | -Use `npx playwright test` for the test runner and `npx playwright codegen` for test generation; they are different command surfaces. +**Design** -### 3) πŸ”Œ Install the MCP route +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Figma | Read designs to build an interface | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md) | -Use a provider-supported client and distinguish the recommended plugin route from manual MCP configuration. +**Monitoring** -1. Pick the [documented Figma route](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) for your client. +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Sentry | Inspect errors and investigate issues | CLI: [`sentry`](https://cli.sentry.dev/) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | -| Client | Figma's recommended route | Manual alternative and scope | -| --- | --- | --- | -| Claude Code | `claude plugin install figma@claude-plugins-official` | `claude mcp add --transport http --scope project figma https://mcp.figma.com/mcp` writes project configuration to `.mcp.json` under `mcpServers` | -| Codex | In the Codex app, open **Plugins**, select **+** next to Figma, then **Install Figma** | `codex mcp add figma --url https://mcp.figma.com/mcp` writes to [`~/.codex/config.toml`](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) under `mcp_servers`; trusted projects may instead use `.codex/config.toml` | -| Cursor | Run `/add-plugin figma` | Manual project configuration uses `.cursor/mcp.json` under `mcpServers` | -| GitHub Copilot in VS Code | Run **MCP: Open Workspace Folder MCP Configuration**, paste Figma's documented server object, then select **Start** | Workspace configuration uses `.vscode/mcp.json` under `servers` | +**Deployment** -```bash -claude plugin install figma@claude-plugins-official -``` +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Vercel | Deploy and read deployment logs | CLI: [`vercel`](https://vercel.com/docs/cli) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | -[Figma accepts only clients in its MCP catalog](https://www.figma.com/mcp-catalog/); do not extrapolate these instructions to an unlisted host. +**Database** -### 4) πŸ” Restrict access - -Use the server's documented authentication, expose only required capabilities, and enforce confirmation for mutations. - -1. If the remote server uses OAuth, authorize it in the client and review the requested scopes; otherwise follow its documented authentication method. -2. Prefer read-only endpoints, toolsets, or allowlists when the workflow only reads. -3. Configure the host to require confirmation for mutating tools; if it cannot, disable write tools or use a provider-enforced read-only mode. - -[GitHub documents](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md#read-only-mode) this VS Code-format server-entry fragment; place it under `servers.github` in `.vscode/mcp.json`, or adapt the wrapper to the selected host: - -```json -{ - "type": "http", - "url": "https://api.githubcopilot.com/mcp/", - "headers": { - "X-MCP-Toolsets": "repos,issues", - "X-MCP-Readonly": "true" - } -} -``` +| Service | Usage | CLI or MCP | Memory | +| --- | --- | --- | --- | +| Supabase | Migrations, local development, database exploration | CLI: [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development; [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md) | -[Notion MCP inherits the connected user's workspace access](https://developers.notion.com/guides/mcp/mcp-security-best-practices), so review every write and any data sent to another tool. +### 2) πŸ”Œ Install and sign in -### 5) βœ… Verify the connection +1. Open your tool's documentation from the table. +2. For a CLI, follow its installation and login instructions. +3. For MCP, follow the provider's instructions for your AI client, then authenticate. +4. Check the account, workspace and requested permissions before granting access. -Verify the configured server, authenticated identity, exposed tools, and one read-only operation before relying on it. +**CLI example: GitHub.** Install `gh` using its [installation guide](https://github.com/cli/cli#installation), then run: -1. Inspect the server through the client, then run a harmless read. - -```text -Claude Code: /mcp -Codex: codex mcp list -Cursor: Settings > Cursor Settings > Tools & MCP -VS Code: MCP: List Servers +```bash +gh auth login +gh auth status ``` -Figma's documented successful Claude Code flow ends with: +**MCP example: Figma in Claude Code.** Figma recommends its plugin: -```text -Authentication successful. Connected to figma +```bash +claude plugin install figma@claude-plugins-official ``` -Use Figma's read-only [`whoami`](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/#whoami-remote-only) tool to confirm the authenticated email, plans, and seat type. +Start a new Claude Code session, run `/mcp`, select Figma, then **Authenticate**. For another client, use [Figma's setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). -### 6) 🧹 Optional rollback: remove local access +Use a read-only mode when you only need to read. Require confirmation for writes; if your client cannot enforce it, disable write tools or use provider-enforced read-only access. -Clearing authentication and local configuration stops the client from using the server. +### 3) βœ… Check the connection -1. Clear authentication before removing the server entry. -2. Remove the server or plugin from the client. +1. Confirm the CLI or MCP is connected to the intended account and workspace. +2. Read one known item, such as a ticket, page or design. +3. Check that the result matches what you see in the service. -| Client | Clear authentication | Remove local configuration | -| --- | --- | --- | -| Claude Code | Run `/mcp`, select Figma, then **Clear authentication** | Plugin: `claude plugin uninstall figma@claude-plugins-official`; manual project server: `claude mcp remove --scope project figma` | -| Codex | Manual server: `codex mcp logout figma` | Plugin: remove Figma in the Codex app's **Plugins** panel; manual server: `codex mcp remove figma` | -| Cursor | Disconnect Figma under **Settings > Cursor Settings > Tools & MCP** | Remove the Figma plugin or its manual `.cursor/mcp.json` entry | -| GitHub Copilot in VS Code | Select the server through **MCP: List Servers** | Uninstall the server or remove its `.vscode/mcp.json` entry | +For GitHub, read the current repository: ```bash -codex mcp logout figma -codex mcp remove figma -``` - -Removing configuration alone does not prove that the OAuth grant was revoked. - -### 7) 🚫 Optional teardown: revoke provider access - -Revoking the provider grant invalidates the remote OAuth authorization independently of local configuration. - -1. For Figma, open [**Settings > Security > Connected apps**](https://help.figma.com/hc/en-us/articles/15021280611607-How-do-I-keep-my-account-secure). -2. Find the MCP client and select **Revoke access**. - -```text -Figma > Settings > Security > Connected apps > Revoke access +gh repo view --json nameWithOwner,url ``` -## Verify +For Figma, ask the assistant to run [`whoami`](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/#whoami-remote-only) and check the returned account. -- The server appears in the chosen client's server list with the expected transport and scope. -- Authentication uses the intended account and workspace; for Figma, `whoami` returns that identity. -- Only the required tools are enabled; mutating calls require confirmation or are disabled. -- For optional rollback or teardown, check authentication clearing, local removal, and provider revocation separately. +To disconnect later, remove the integration from your client and revoke its access in the service's account settings. From 5db62f8d18b65a220ce0f54e73592ba8e26b7235 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:02:30 +0800 Subject: [PATCH 02/16] docs(aidd-context): show connection alternatives and verification prompt --- .../assets/recipes/mcp-installation.md | 86 +++++++++++-------- 1 file changed, 48 insertions(+), 38 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index c7ccfd86f..0c26b7ddd 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -1,6 +1,6 @@ # Connect your services -Choose a CLI or MCP server so your AI assistant can work with your team's services. +Choose a CLI, MCP server or native tool so your AI assistant can work with your team's services. @@ -8,61 +8,66 @@ Choose a CLI or MCP server so your AI assistant can work with your team's servic ### 1) πŸ”Ž Choose the tool -Start with the CLI when it covers your task and your assistant can run shell commands. Use MCP when you need its tools inside the assistant. +Start with the CLI when it covers your task and your assistant can run shell commands. Use MCP or a native tool when you need it inside the assistant. Choose one option per service. Memory links open the AIDD templates for the corresponding files in your project's `aidd_docs/memory/`. **Version control** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| GitHub | Issues, PRs, releases, CI runs | CLI: [`gh`](https://cli.github.com/manual/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | -| GitLab | Issues, merge requests, pipelines | CLI: [`glab`](https://docs.gitlab.com/cli/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| GitHub | Issues, PRs, releases, CI runs | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | +| GitLab | Issues, merge requests, pipelines | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | +| Bitbucket | Search and read repository context | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | **Ticketing** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Jira Cloud | Search, create, update tickets | CLI: [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | -| Linear | Search, create, update tickets | [Linear MCP](https://linear.app/docs/mcp) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Jira Cloud | Search, create, update tickets | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | +| Linear | Search, create, update tickets | β€” | [Linear MCP](https://linear.app/docs/mcp) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | **Documentation and workspace** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Confluence | Search and edit team documentation | [Atlassian MCP](https://www.atlassian.com/platform/rovo-mcp) | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | -| Notion | Search and edit workspace pages | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp); CLI: [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | -| Google Workspace | Drive, Docs, Sheets, Gmail, Calendar | CLI: [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Confluence | Search and edit team documentation | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | +| Notion | Search and edit workspace pages | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | +| Google Workspace | Drive, Docs, Sheets, Gmail, Calendar | [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | β€” | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | **Browser** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Playwright | Browse and inspect a website | CLI: [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Playwright | Browse and inspect a website | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | +| Claude in Chrome | Inspect and validate the web application | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | +| Cursor Browser | Inspect and validate the web application | β€” | [Built-in browser](https://prod.cursor.com/docs/agent/tools/browser) | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | **Design** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Figma | Read designs to build an interface | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Figma | Read designs to build an interface | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md) | **Monitoring** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Sentry | Inspect errors and investigate issues | CLI: [`sentry`](https://cli.sentry.dev/) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Sentry | Inspect errors and investigate issues | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://github.com/getsentry/toolkit) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | **Deployment** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Vercel | Deploy and read deployment logs | CLI: [`vercel`](https://vercel.com/docs/cli) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Vercel | Deploy and read deployment logs | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | **Database** -| Service | Usage | CLI or MCP | Memory | -| --- | --- | --- | --- | -| Supabase | Migrations, local development, database exploration | CLI: [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development; [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md) | +| Service | Usage | CLI | MCP or native tool | Memory | +| --- | --- | --- | --- | --- | +| Supabase | Migrations, local development, database exploration | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md) | + +Add any other services your team uses to the relevant table. ### 2) πŸ”Œ Install and sign in @@ -90,16 +95,21 @@ Use a read-only mode when you only need to read. Require confirmation for writes ### 3) βœ… Check the connection -1. Confirm the CLI or MCP is connected to the intended account and workspace. -2. Read one known item, such as a ticket, page or design. -3. Check that the result matches what you see in the service. +Run this prompt in your assistant: -For GitHub, read the current repository: +```text +Check this project's connections against the tables above and aidd_docs/memory/. +For each needed service, use one available tool, confirm the account and target, +then perform one read. For the browser, open the application and read its content. +Change nothing and expose no secrets. Include missing required connections. +Mark missing evidence as unverified. +Fill this table, one row per service: -```bash -gh repo view --json nameWithOwner,url -``` +| Service | Tool | Account / target | Read evidence | Status | Next step | +| --- | --- | --- | --- | --- | --- | +| | | | | | | -For Figma, ask the assistant to run [`whoami`](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/#whoami-remote-only) and check the returned account. +βœ… Read passed Β· ❌ Failed Β· ⚠️ Unverified Β· ⏭️ Not needed +``` To disconnect later, remove the integration from your client and revoke its access in the service's account settings. From 4e22b0c20b70e01532f4031b9f591fd7dd31e0e9 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:08:47 +0800 Subject: [PATCH 03/16] docs(aidd-context): move memory links to category descriptions --- .../assets/recipes/mcp-installation.md | 78 +++++++++++-------- 1 file changed, 47 insertions(+), 31 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index 0c26b7ddd..72bc38328 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -14,58 +14,74 @@ Memory links open the AIDD templates for the corresponding files in your project **Version control** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| GitHub | Issues, PRs, releases, CI runs | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | -| GitLab | Issues, merge requests, pipelines | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | -| Bitbucket | Search and read repository context | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md) | +> Repositories and code reviews; conventions in [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| GitHub | Issues, PRs, releases, CI runs | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | +| GitLab | Issues, merge requests, pipelines | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | +| Bitbucket | Search and read repository context | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | **Ticketing** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Jira Cloud | Search, create, update tickets | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | -| Linear | Search, create, update tickets | β€” | [Linear MCP](https://linear.app/docs/mcp) | [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md) | +> Work items and planning; workflow in [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Jira Cloud | Search, create, update tickets | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Linear | Search, create, update tickets | β€” | [Linear MCP](https://linear.app/docs/mcp) | **Documentation and workspace** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Confluence | Search and edit team documentation | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | -| Notion | Search and edit workspace pages | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | -| Google Workspace | Drive, Docs, Sheets, Gmail, Calendar | [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | β€” | [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md) | +> Team knowledge and workspace tools; access map in [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Confluence | Search and edit team documentation | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Notion | Search and edit workspace pages | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | +| Google Workspace | Drive, Docs, Sheets, Gmail, Calendar | [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | β€” | **Browser** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Playwright | Browse and inspect a website | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | -| Claude in Chrome | Inspect and validate the web application | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | -| Cursor Browser | Inspect and validate the web application | β€” | [Built-in browser](https://prod.cursor.com/docs/agent/tools/browser) | [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md) | +> Web navigation and validation; test setup in [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Playwright | Browse and inspect a website | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | +| Claude in Chrome | Inspect and validate the web application | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | +| Cursor Browser | Inspect and validate the web application | β€” | [Built-in browser](https://prod.cursor.com/docs/agent/tools/browser) | **Design** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Figma | Read designs to build an interface | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md) | +> Design context for implementation; UI conventions in [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Figma | Read designs to build an interface | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | **Monitoring** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Sentry | Inspect errors and investigate issues | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://github.com/getsentry/toolkit) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | +> Errors and incident investigation; monitoring setup in [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Sentry | Inspect errors and investigate issues | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://github.com/getsentry/toolkit) | **Deployment** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Vercel | Deploy and read deployment logs | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md) | +> Releases and deployment logs; environments and pipeline in [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Vercel | Deploy and read deployment logs | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | **Database** -| Service | Usage | CLI | MCP or native tool | Memory | -| --- | --- | --- | --- | --- | -| Supabase | Migrations, local development, database exploration | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md) | +> Migrations and database exploration; data model and conventions in [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). + +| Service | Usage | CLI | MCP or native tool | +| --- | --- | --- | --- | +| Supabase | Migrations, local development, database exploration | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | Add any other services your team uses to the relevant table. From 8b1b967c90077c97f09ee91de96e01a3c20a7d6b Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:11:53 +0800 Subject: [PATCH 04/16] docs(aidd-context): simplify connection tables and category descriptions --- .../assets/recipes/mcp-installation.md | 78 +++++++++---------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index 72bc38328..aa3b50854 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -14,74 +14,74 @@ Memory links open the AIDD templates for the corresponding files in your project **Version control** -> Repositories and code reviews; conventions in [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). +> Work with repositories, pull requests and CI runs. Project conventions: [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| GitHub | Issues, PRs, releases, CI runs | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | -| GitLab | Issues, merge requests, pipelines | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | -| Bitbucket | Search and read repository context | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| GitHub | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | +| GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | +| Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | **Ticketing** -> Work items and planning; workflow in [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). +> Find, create and update tickets. Team workflow: [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Jira Cloud | Search, create, update tickets | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | -| Linear | Search, create, update tickets | β€” | [Linear MCP](https://linear.app/docs/mcp) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | **Documentation and workspace** -> Team knowledge and workspace tools; access map in [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). +> Access team documents, files, email and calendars. Connected tools: [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Confluence | Search and edit team documentation | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | -| Notion | Search and edit workspace pages | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | -| Google Workspace | Drive, Docs, Sheets, Gmail, Calendar | [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | β€” | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | +| Google Workspace | [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | β€” | **Browser** -> Web navigation and validation; test setup in [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). +> Open the application and check its behavior in a browser. Test instructions: [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Playwright | Browse and inspect a website | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | -| Claude in Chrome | Inspect and validate the web application | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | -| Cursor Browser | Inspect and validate the web application | β€” | [Built-in browser](https://prod.cursor.com/docs/agent/tools/browser) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | +| Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | +| Cursor Browser | β€” | [Built-in browser](https://prod.cursor.com/docs/agent/tools/browser) | **Design** -> Design context for implementation; UI conventions in [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). +> Read designs and follow the project's design system. UI guidelines: [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Figma | Read designs to build an interface | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | **Monitoring** -> Errors and incident investigation; monitoring setup in [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). +> Read application errors and investigate failures. Monitoring configuration: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Sentry | Inspect errors and investigate issues | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://github.com/getsentry/toolkit) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://github.com/getsentry/toolkit) | **Deployment** -> Releases and deployment logs; environments and pipeline in [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). +> Deploy the application and inspect deployment logs. Deployment instructions: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Vercel | Deploy and read deployment logs | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | **Database** -> Migrations and database exploration; data model and conventions in [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). +> Explore the database and run migrations. Database conventions: [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). -| Service | Usage | CLI | MCP or native tool | -| --- | --- | --- | --- | -| Supabase | Migrations, local development, database exploration | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | Add any other services your team uses to the relevant table. From fdcd977218c86db79337ace2982af143c3fbf13a Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:22:09 +0800 Subject: [PATCH 05/16] feat(aidd-context): verify service connections from project memory --- plugins/aidd-context/CATALOG.md | 4 +- .../skills/02-project-memory/SKILL.md | 8 +++- .../actions/05-verify-connection.md | 43 +++++++++++++++++++ .../assets/connection-report.md | 9 ++++ .../assets/recipes/mcp-installation.md | 20 +++------ 5 files changed, 67 insertions(+), 17 deletions(-) create mode 100644 plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md create mode 100644 plugins/aidd-context/skills/02-project-memory/assets/connection-report.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 06c1317db..f2d036ae5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -75,6 +75,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write.md](skills/02-project-memory/actions/02-write.md) | - | | `actions` | [03-check.md](skills/02-project-memory/actions/03-check.md) | - | | `actions` | [04-sync.md](skills/02-project-memory/actions/04-sync.md) | - | +| `actions` | [05-verify-connection.md](skills/02-project-memory/actions/05-verify-connection.md) | - | +| `assets` | [connection-report.md](skills/02-project-memory/assets/connection-report.md) | - | | `assets` | [report.md](skills/02-project-memory/assets/report.md) | - | | `assets` | [scan-summary.md](skills/02-project-memory/assets/scan-summary.md) | - | | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - | @@ -85,7 +87,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [review-protocol.md](skills/02-project-memory/references/review-protocol.md) | - | | `references` | [structure.md](skills/02-project-memory/references/structure.md) | - | | `references` | [tools.md](skills/02-project-memory/references/tools.md) | - | -| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file.` | +| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file.` | #### `skills/03-context-generate` diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index e854cb94b..e4b3796c7 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -1,7 +1,7 @@ --- name: 02-project-memory -description: Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file. -argument-hint: setup | refresh | rewire +description: Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file. +argument-hint: setup | refresh | rewire | connections --- # Project Memory @@ -11,6 +11,9 @@ flowchart LR new([no argument, or setup]) --> scan --> write --> sync --> wired([memory wired]) update([refresh]) --> scan --> check --> write rewire([rewire]) --> sync + connections([verify connections]) --> verify-connection + verify-connection -->|checked| reported([connection report]) + verify-connection -->|no memory bank| missing([memory missing]) scan -.-> empty([nothing to remember]) ``` @@ -24,6 +27,7 @@ Run the flow above, reading only the next action file. | write | write the memory | | check | show what drifted, change nothing | | sync | pick the tools, wire it in | +| verify-connection | verify the assistant's service access | ## Transversal rules diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md new file mode 100644 index 000000000..19c6d1eab --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -0,0 +1,43 @@ +# 05 - Verify Connection + +Verify the assistant's access to the services declared in project memory. + +## Input + +The bank in `aidd_docs/memory/`, and an optional service to check. + +## Output + +A connection report printed using [connection-report.md](../assets/connection-report.md). + +## Process + +1. **Scope.** Read the service map and relevant memory files to identify the assistant's expected tools, accounts and targets. + - No memory bank: report it missing and stop. + - Include required access that the memory describes but this session lacks. + - Include browser access when the project requires web validation. +2. **Inspect.** Check one declared CLI, MCP or native tool per service against its official documentation. + - No available tool: report the missing access without installing anything. + - Unknown account or target: mark it unverified unless a read can resolve it. +3. **Read.** Confirm the account and target, then read one known item through the selected tool. + - Browser: open the application and read visible content. + - Database: read metadata without changing data or running migrations. + - No writes, configuration changes, login flows or secret output. + - Continue with the other services when a check fails. +4. **Report.** Fill [connection-report.md](../assets/connection-report.md) from the observed results. + - A configured tool alone never proves access. + - A successful read never proves write permissions. + - Keep these session results out of the durable memory bank. + +## Test + +| Case | Pass | +| --- | --- | +| Declared service | its row names the tool, account, target and observed read | +| Required access missing | its row reports failure and the next action | +| Read fails | its row reports the error and other services are still checked | +| Identity or target unresolved | its row is unverified, never successful | +| Tool only configured | its row is unverified until a read succeeds | +| Browser needed | its evidence names the application and visible content read | +| Database checked | only metadata was read | +| Run completes | no data, configuration or memory file changed | diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md new file mode 100644 index 000000000..f3a5d4b4c --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -0,0 +1,9 @@ +# Connection Report + + + +| Service | Tool | Account / target | Read evidence | Status | Next step | +| --- | --- | --- | --- | --- | --- | +| | | | | | | + +βœ… Read passed Β· ❌ Failed or missing Β· ⚠️ Unverified Β· ⏭️ Not needed diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index aa3b50854..7f255e09f 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -2,6 +2,8 @@ Choose a CLI, MCP server or native tool so your AI assistant can work with your team's services. +Each category points to the project memory that records how your team uses those services. This gives the assistant the right repository, workspace and conventions for its work. + ## Steps to connect your services @@ -28,6 +30,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Service | CLI | MCP or native tool | | --- | --- | --- | +| GitHub Issues | [`gh issue`](https://cli.github.com/manual/gh_issue) | [GitHub MCP](https://github.com/github/github-mcp-server) | | Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | | Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | @@ -39,7 +42,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | | Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | -| Google Workspace | [`gws`](https://github.com/googleworkspace/cli), not officially supported by Google | β€” | +| Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | **Browser** @@ -111,21 +114,10 @@ Use a read-only mode when you only need to read. Require confirmation for writes ### 3) βœ… Check the connection -Run this prompt in your assistant: +Ask your assistant to verify the connections declared in project memory: ```text -Check this project's connections against the tables above and aidd_docs/memory/. -For each needed service, use one available tool, confirm the account and target, -then perform one read. For the browser, open the application and read its content. -Change nothing and expose no secrets. Include missing required connections. -Mark missing evidence as unverified. -Fill this table, one row per service: - -| Service | Tool | Account / target | Read evidence | Status | Next step | -| --- | --- | --- | --- | --- | --- | -| | | | | | | - -βœ… Read passed Β· ❌ Failed Β· ⚠️ Unverified Β· ⏭️ Not needed +Verify this project's service connections against aidd_docs/memory/. ``` To disconnect later, remove the integration from your client and revoke its access in the service's account settings. From 38bbd3545a189af1a31435a850ab50377715aa09 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:23:36 +0800 Subject: [PATCH 06/16] fix(aidd-context): report connections once per category --- .../actions/05-verify-connection.md | 10 ++++++++-- .../02-project-memory/assets/connection-report.md | 15 +++++++++++---- .../12-cook/assets/recipes/mcp-installation.md | 3 ++- 3 files changed, 21 insertions(+), 7 deletions(-) diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md index 19c6d1eab..e371faa82 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -24,7 +24,10 @@ A connection report printed using [connection-report.md](../assets/connection-re - Database: read metadata without changing data or running migrations. - No writes, configuration changes, login flows or secret output. - Continue with the other services when a check fails. -4. **Report.** Fill [connection-report.md](../assets/connection-report.md) from the observed results. +4. **Report.** Fill [connection-report.md](../assets/connection-report.md) with one row per category, grouping its required services. + - Keep every category; mark unused categories as not needed. + - A category passes only when every required service was read successfully. + - A failure or missing access takes precedence over an unverified result. - A configured tool alone never proves access. - A successful read never proves write permissions. - Keep these session results out of the durable memory bank. @@ -33,7 +36,10 @@ A connection report printed using [connection-report.md](../assets/connection-re | Case | Pass | | --- | --- | -| Declared service | its row names the tool, account, target and observed read | +| Report | exactly one row per template category, with its services grouped | +| Declared service | its category row names the tool, account, target and observed read | +| Several required services | the category passes only when every required read succeeds | +| Category unused | its row remains and is marked not needed | | Required access missing | its row reports failure and the next action | | Read fails | its row reports the error and other services are still checked | | Identity or target unresolved | its row is unverified, never successful | diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md index f3a5d4b4c..93bfe847a 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -1,9 +1,16 @@ # Connection Report - + -| Service | Tool | Account / target | Read evidence | Status | Next step | +| Category | Service / tool | Account / target | Read evidence | Status | Next step | | --- | --- | --- | --- | --- | --- | -| | | | | | | +| Version control | | | | | | +| Ticketing | | | | | | +| Documentation and workspace | | | | | | +| Browser | | | | | | +| Design | | | | | | +| Monitoring | | | | | | +| Deployment | | | | | | +| Database | | | | | | -βœ… Read passed Β· ❌ Failed or missing Β· ⚠️ Unverified Β· ⏭️ Not needed +βœ… All required reads passed Β· ❌ Failed or missing Β· ⚠️ Unverified Β· ⏭️ Not needed diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index 7f255e09f..efc931572 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -117,7 +117,8 @@ Use a read-only mode when you only need to read. Require confirmation for writes Ask your assistant to verify the connections declared in project memory: ```text -Verify this project's service connections against aidd_docs/memory/. +Verify this project's connections against aidd_docs/memory/. +Report one row per category. ``` To disconnect later, remove the integration from your client and revoke its access in the service's account settings. From 0796d4244cc49de2daa35cd1b57a568a8c3e3a01 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:45:28 +0800 Subject: [PATCH 07/16] fix(aidd-context): clarify connection verification scope and verdicts --- .../actions/05-verify-connection.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md index e371faa82..18855080e 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -4,7 +4,7 @@ Verify the assistant's access to the services declared in project memory. ## Input -The bank in `aidd_docs/memory/`, and an optional service to check. +The bank in `aidd_docs/memory/`. ## Output @@ -12,10 +12,11 @@ A connection report printed using [connection-report.md](../assets/connection-re ## Process -1. **Scope.** Read the service map and relevant memory files to identify the assistant's expected tools, accounts and targets. +1. **Scope.** Read `aidd_docs/memory/ecosystem.md` and its referenced memory files to identify the assistant's expected tools, accounts and targets. + - Check assistant access, excluding human-only tools and application runtime connections. - No memory bank: report it missing and stop. - Include required access that the memory describes but this session lacks. - - Include browser access when the project requires web validation. + - Include browser access when the project's `testing.md` requires web validation. 2. **Inspect.** Check one declared CLI, MCP or native tool per service against its official documentation. - No available tool: report the missing access without installing anything. - Unknown account or target: mark it unverified unless a read can resolve it. @@ -24,7 +25,7 @@ A connection report printed using [connection-report.md](../assets/connection-re - Database: read metadata without changing data or running migrations. - No writes, configuration changes, login flows or secret output. - Continue with the other services when a check fails. -4. **Report.** Fill [connection-report.md](../assets/connection-report.md) with one row per category, grouping its required services. +4. **Report.** Fill `connection-report.md` with one row per category, grouping its required services. - Keep every category; mark unused categories as not needed. - A category passes only when every required service was read successfully. - A failure or missing access takes precedence over an unverified result. @@ -42,8 +43,8 @@ A connection report printed using [connection-report.md](../assets/connection-re | Category unused | its row remains and is marked not needed | | Required access missing | its row reports failure and the next action | | Read fails | its row reports the error and other services are still checked | -| Identity or target unresolved | its row is unverified, never successful | -| Tool only configured | its row is unverified until a read succeeds | +| Identity or target unresolved | its category cannot pass; failure takes precedence over unverified | +| Tool only configured | its category cannot pass until the required read succeeds | | Browser needed | its evidence names the application and visible content read | | Database checked | only metadata was read | | Run completes | no data, configuration or memory file changed | From e6ee8a81c8a92794742358a7f71994993f7068a7 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 15:54:50 +0800 Subject: [PATCH 08/16] fix(aidd-context): use verify as the connection check entry --- plugins/aidd-context/skills/02-project-memory/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index e4b3796c7..d022b5213 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -1,7 +1,7 @@ --- name: 02-project-memory description: Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file. -argument-hint: setup | refresh | rewire | connections +argument-hint: setup | refresh | rewire | verify --- # Project Memory @@ -11,7 +11,7 @@ flowchart LR new([no argument, or setup]) --> scan --> write --> sync --> wired([memory wired]) update([refresh]) --> scan --> check --> write rewire([rewire]) --> sync - connections([verify connections]) --> verify-connection + verify([verify]) --> verify-connection verify-connection -->|checked| reported([connection report]) verify-connection -->|no memory bank| missing([memory missing]) scan -.-> empty([nothing to remember]) From e4886674b5c23ceb7cdbfeda48337f0ea89bdd07 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 15:58:18 +0800 Subject: [PATCH 09/16] feat(aidd-context): add database clients and simplify connection reports --- .../actions/05-verify-connection.md | 9 +++---- .../assets/connection-report.md | 24 +++++++++---------- .../assets/recipes/mcp-installation.md | 2 ++ 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md index 18855080e..056b0eb50 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -18,7 +18,7 @@ A connection report printed using [connection-report.md](../assets/connection-re - Include required access that the memory describes but this session lacks. - Include browser access when the project's `testing.md` requires web validation. 2. **Inspect.** Check one declared CLI, MCP or native tool per service against its official documentation. - - No available tool: report the missing access without installing anything. + - No available tool or configured connection: mark it not configured without installing or connecting anything. - Unknown account or target: mark it unverified unless a read can resolve it. 3. **Read.** Confirm the account and target, then read one known item through the selected tool. - Browser: open the application and read visible content. @@ -28,7 +28,8 @@ A connection report printed using [connection-report.md](../assets/connection-re 4. **Report.** Fill `connection-report.md` with one row per category, grouping its required services. - Keep every category; mark unused categories as not needed. - A category passes only when every required service was read successfully. - - A failure or missing access takes precedence over an unverified result. + - For mixed results, use this precedence: read failed, not configured, unverified. + - Name the affected service, the shortest useful error and one corrective action. - A configured tool alone never proves access. - A successful read never proves write permissions. - Keep these session results out of the durable memory bank. @@ -41,9 +42,9 @@ A connection report printed using [connection-report.md](../assets/connection-re | Declared service | its category row names the tool, account, target and observed read | | Several required services | the category passes only when every required read succeeds | | Category unused | its row remains and is marked not needed | -| Required access missing | its row reports failure and the next action | +| Required access not configured | its category is marked not configured with the next action | | Read fails | its row reports the error and other services are still checked | -| Identity or target unresolved | its category cannot pass; failure takes precedence over unverified | +| Identity or target unresolved | its category cannot pass; failed or unconfigured access takes precedence | | Tool only configured | its category cannot pass until the required read succeeds | | Browser needed | its evidence names the application and visible content read | | Database checked | only metadata was read | diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md index 93bfe847a..28f95befe 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -1,16 +1,16 @@ # Connection Report - + -| Category | Service / tool | Account / target | Read evidence | Status | Next step | -| --- | --- | --- | --- | --- | --- | -| Version control | | | | | | -| Ticketing | | | | | | -| Documentation and workspace | | | | | | -| Browser | | | | | | -| Design | | | | | | -| Monitoring | | | | | | -| Deployment | | | | | | -| Database | | | | | | +| Category | Tool / target | Status | Evidence / next step | +| --- | --- | --- | --- | +| Version control | | | | +| Ticketing | | | | +| Documentation and workspace | | | | +| Browser | | | | +| Design | | | | +| Monitoring | | | | +| Deployment | | | | +| Database | | | | -βœ… All required reads passed Β· ❌ Failed or missing Β· ⚠️ Unverified Β· ⏭️ Not needed +βœ… All required reads passed Β· ❌ Read failed Β· πŸ”Œ Not configured Β· ⚠️ Unverified Β· ⏭️ Not needed diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index efc931572..c02f040f9 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -84,6 +84,8 @@ Memory links open the AIDD templates for the corresponding files in your project | Service | CLI | MCP or native tool | | --- | --- | --- | +| PostgreSQL | [`psql`](https://www.postgresql.org/docs/current/app-psql.html) | β€” | +| MongoDB | [`mongosh`](https://www.mongodb.com/docs/mongodb-shell/) | [MongoDB MCP](https://www.mongodb.com/docs/mcp-server/) | | Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | Add any other services your team uses to the relevant table. From 300ee4f9eb921b0fc48c48116d984950025c9862 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 16:03:32 +0800 Subject: [PATCH 10/16] docs(aidd-context): link directly to official connection guides --- .../skills/12-cook/assets/recipes/mcp-installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md index c02f040f9..d8da4458c 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -52,7 +52,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | | Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | -| Cursor Browser | β€” | [Built-in browser](https://prod.cursor.com/docs/agent/tools/browser) | +| Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | **Design** @@ -68,7 +68,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Service | CLI | MCP or native tool | | --- | --- | --- | -| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://github.com/getsentry/toolkit) | +| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | **Deployment** From 8419382ddad4c940a241ca2145666892fadd6f01 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 16:12:58 +0800 Subject: [PATCH 11/16] refactor(aidd-context): simplify service setup and connection verification --- README.md | 4 +- .../domain/recipes/recipe-validation.ts | 10 +++-- .../recipes/recipe-validation.unit.test.ts | 37 +++++++++++++++- .../skills/02-project-memory/SKILL.md | 4 +- .../actions/05-verify-connection.md | 43 +++++-------------- .../assets/connection-report.md | 2 +- ...cp-installation.md => connect-services.md} | 25 +++++------ .../assets/recipes/token-optimization.md | 2 +- 8 files changed, 72 insertions(+), 55 deletions(-) rename plugins/aidd-context/skills/12-cook/assets/recipes/{mcp-installation.md => connect-services.md} (92%) diff --git a/README.md b/README.md index 362d9c5e1..0b68a7544 100644 --- a/README.md +++ b/README.md @@ -236,7 +236,7 @@ Start with a functional need or User Story, then track it as an issue or ticket before planning. Shipping follows the project's own delivery process. Capture a learning only when it is durable enough to improve the next feature. -> 🍳 **More flows** β†’ bundled recipes: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). +> 🍳 **More flows** β†’ bundled recipes: [Connect your services](plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). ## 🧩 Plugins @@ -338,7 +338,7 @@ Full catalog β†’ [`CATALOG.md`](docs/CATALOG.md). | | | | --- | --- | -| 🍳 **Recipes** | Bundled how-to sheets: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. | +| 🍳 **Recipes** | Bundled how-to sheets: [Connect your services](plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. | | πŸ›οΈ **[Architecture](docs/ARCHITECTURE.md)** | How the framework composes: plugins, skills, hooks, agents. | | 🧩 **[Create a plugin](docs/CREATE_PLUGIN.md)** | Build and publish your own. | | πŸ›’ **[Marketplace](docs/MARKETPLACE.md)** | Install scopes and versioning. | diff --git a/cli/src/contexts/framework/domain/recipes/recipe-validation.ts b/cli/src/contexts/framework/domain/recipes/recipe-validation.ts index 3cff22b1b..879b1515e 100644 --- a/cli/src/contexts/framework/domain/recipes/recipe-validation.ts +++ b/cli/src/contexts/framework/domain/recipes/recipe-validation.ts @@ -394,8 +394,10 @@ function checkSteps( ); const steps: RecipeStep[] = []; const categories: Heading[] = []; + let directStep: RecipeStep | undefined; for (const heading of scopedHeadings) { + if (heading.depth === 3) directStep = undefined; const source = `${"#".repeat(heading.depth)} ${heading.text}`; const match = source.match(STEP_PATTERN); if (match) { @@ -409,7 +411,9 @@ function checkSteps( "Add one meaningful emoji between the step number and title." ); } - steps.push({ ...heading, number: Number.parseInt(match[2], 10), icon, title: match[4] }); + const step = { ...heading, number: Number.parseInt(match[2], 10), icon, title: match[4] }; + steps.push(step); + if (heading.depth === 3) directStep = step; continue; } @@ -423,13 +427,13 @@ function checkSteps( ); } else if (heading.depth === 3) { categories.push(heading); - } else { + } else if (!directStep) { addFinding( findings, file, heading.line, "category-depth", - "Use level 3 for a category and level 4 only for its numbered steps." + "Use level 4 for numbered category steps or subsections of a direct numbered step." ); } } diff --git a/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts b/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts index d2c52df9a..41c152679 100644 --- a/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts +++ b/cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts @@ -104,7 +104,7 @@ test("categories require level-four steps and cannot parent earlier steps", () = recipe(command, "### Beginner\n\n#### Unnumbered step"), "category-depth", 9, - "Use level 3 for a category and level 4 only for its numbered steps." + "Use level 4 for numbered category steps or subsections of a direct numbered step." ); }); @@ -117,6 +117,41 @@ test("direct steps stay at level three", () => { ); }); +test("direct numbered steps allow unnumbered level-four subsections", () => { + const content = recipe( + `#### Version control\n\n${command}\n\n#### Database\n\n${command}\n\n### 2) πŸ”Œ Connect\n\n#### Authentication\n\n${command}` + ); + assert.deepEqual(inspectRecipe(file, content).findings, []); +}); + +test("unnumbered level-four subsections require a direct numbered parent", () => { + for (const heading of [ + "#### Orphan subsection", + "### 1. βœ… Check readiness\n\n#### Subsection", + "### 1) βœ… Check readiness\n\n### Beginner\n\n#### Subsection", + "### Beginner\n\n#### 1) βœ… Check readiness\n\n#### Subsection", + ]) { + assert.equal( + inspectRecipe(file, recipe(command, heading)).findings.some( + (item) => item.rule === "category-depth" + ), + true + ); + } +}); + +test.each(["#### 2. πŸ”Œ Connect", "#### 2 πŸ”Œ Connect"])( + "subsections do not hide malformed numbered step heading %s", + (heading) => { + finding( + recipe(`${heading}\n\n${command}`), + "step-heading", + 9, + "Use `### N) Title`, or `#### N) Title` below a category." + ); + } +); + test("step numbering continues across categories instead of restarting", () => { const content = recipe( `${command}\n\n### Advanced\n\n#### 1) πŸ”¬ Inspect output\n\n${command}`, diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index d022b5213..78f705eb5 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -12,8 +12,8 @@ flowchart LR update([refresh]) --> scan --> check --> write rewire([rewire]) --> sync verify([verify]) --> verify-connection - verify-connection -->|checked| reported([connection report]) - verify-connection -->|no memory bank| missing([memory missing]) + verify-connection -->|report| reported([connection report]) + verify-connection -->|memory missing| missing([memory missing]) scan -.-> empty([nothing to remember]) ``` diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md index 056b0eb50..58cf3bba1 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -1,6 +1,6 @@ # 05 - Verify Connection -Verify the assistant's access to the services declared in project memory. +Check the assistant's service connections and fill the report. ## Input @@ -8,44 +8,21 @@ The bank in `aidd_docs/memory/`. ## Output -A connection report printed using [connection-report.md](../assets/connection-report.md). +A printed report using [connection-report.md](../assets/connection-report.md). ## Process -1. **Scope.** Read `aidd_docs/memory/ecosystem.md` and its referenced memory files to identify the assistant's expected tools, accounts and targets. - - Check assistant access, excluding human-only tools and application runtime connections. +1. **Read.** Read `ecosystem.md`, its referenced memory files and `testing.md` to identify required assistant access and targets. - No memory bank: report it missing and stop. - - Include required access that the memory describes but this session lacks. - - Include browser access when the project's `testing.md` requires web validation. -2. **Inspect.** Check one declared CLI, MCP or native tool per service against its official documentation. - - No available tool or configured connection: mark it not configured without installing or connecting anything. - - Unknown account or target: mark it unverified unless a read can resolve it. -3. **Read.** Confirm the account and target, then read one known item through the selected tool. - - Browser: open the application and read visible content. - - Database: read metadata without changing data or running migrations. - - No writes, configuration changes, login flows or secret output. - - Continue with the other services when a check fails. -4. **Report.** Fill `connection-report.md` with one row per category, grouping its required services. - - Keep every category; mark unused categories as not needed. - - A category passes only when every required service was read successfully. - - For mixed results, use this precedence: read failed, not configured, unverified. - - Name the affected service, the shortest useful error and one corrective action. - - A configured tool alone never proves access. - - A successful read never proves write permissions. - - Keep these session results out of the durable memory bank. +2. **Check.** Use the available CLI, MCP or native tools to confirm the account and target, then perform one read per required service. + - Read browser content or database metadata where relevant. + - No writes, installs, login flows, configuration changes or secret output. +3. **Report.** Fill `connection-report.md` from observed results, with one row per category. ## Test | Case | Pass | | --- | --- | -| Report | exactly one row per template category, with its services grouped | -| Declared service | its category row names the tool, account, target and observed read | -| Several required services | the category passes only when every required read succeeds | -| Category unused | its row remains and is marked not needed | -| Required access not configured | its category is marked not configured with the next action | -| Read fails | its row reports the error and other services are still checked | -| Identity or target unresolved | its category cannot pass; failed or unconfigured access takes precedence | -| Tool only configured | its category cannot pass until the required read succeeds | -| Browser needed | its evidence names the application and visible content read | -| Database checked | only metadata was read | -| Run completes | no data, configuration or memory file changed | +| Report | all eight categories appear, with observed evidence or a missing access | +| Failed or unavailable read | no success is claimed; other services are still checked | +| Completion | no data, configuration or memory file changed | diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md index 28f95befe..538476632 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -1,6 +1,6 @@ # Connection Report - + | Category | Tool / target | Status | Evidence / next step | | --- | --- | --- | --- | diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md similarity index 92% rename from plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md rename to plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md index d8da4458c..7509e383f 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -14,7 +14,7 @@ Start with the CLI when it covers your task and your assistant can run shell com Memory links open the AIDD templates for the corresponding files in your project's `aidd_docs/memory/`. -**Version control** +#### Version control > Work with repositories, pull requests and CI runs. Project conventions: [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). @@ -24,7 +24,7 @@ Memory links open the AIDD templates for the corresponding files in your project | GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | | Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | -**Ticketing** +#### Ticketing > Find, create and update tickets. Team workflow: [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). @@ -34,7 +34,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | | Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | -**Documentation and workspace** +#### Documentation and workspace > Access team documents, files, email and calendars. Connected tools: [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). @@ -44,7 +44,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | | Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | -**Browser** +#### Browser > Open the application and check its behavior in a browser. Test instructions: [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). @@ -54,7 +54,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | | Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | -**Design** +#### Design > Read designs and follow the project's design system. UI guidelines: [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). @@ -62,7 +62,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | -**Monitoring** +#### Monitoring > Read application errors and investigate failures. Monitoring configuration: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). @@ -70,7 +70,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | -**Deployment** +#### Deployment > Deploy the application and inspect deployment logs. Deployment instructions: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). @@ -78,7 +78,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | -**Database** +#### Database > Explore the database and run migrations. Database conventions: [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). @@ -92,10 +92,11 @@ Add any other services your team uses to the relevant table. ### 2) πŸ”Œ Install and sign in -1. Open your tool's documentation from the table. -2. For a CLI, follow its installation and login instructions. -3. For MCP, follow the provider's instructions for your AI client, then authenticate. -4. Check the account, workspace and requested permissions before granting access. +1. Check existing connections first; in [Claude Code](https://code.claude.com/docs/en/mcp#managing-your-servers), run `/mcp` to see MCP server status. +2. Open your tool's documentation from the table. +3. For a CLI, follow its installation and login instructions. +4. For MCP, follow the provider's instructions for your AI client, then authenticate. +5. Check the account, workspace and requested permissions before granting access. **CLI example: GitHub.** Install `gh` using its [installation guide](https://github.com/cli/cli#installation), then run: diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md index 1449a3466..3bd67e561 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md @@ -449,7 +449,7 @@ enabled = false Set `enabled = true` or remove the override to restore the server. -See [Claude Code MCP](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search), [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), and [`mcp-installation.md`](mcp-installation.md). +See [Claude Code MCP](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search), [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), and [`connect-services.md`](connect-services.md). ### πŸ”΄ Expert From 4997b66d5a4e7dedfec381d92a0ba1baaa8da3ca Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 16:28:25 +0800 Subject: [PATCH 12/16] docs(aidd-context): clarify setup actions and label service categories --- .../assets/recipes/connect-services.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md index 7509e383f..0bee0ec9b 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -10,11 +10,11 @@ Each category points to the project memory that records how your team uses those ### 1) πŸ”Ž Choose the tool -Start with the CLI when it covers your task and your assistant can run shell commands. Use MCP or a native tool when you need it inside the assistant. Choose one option per service. +Reuse existing connections. For each service your project uses, start with one option that covers your task. Prefer a CLI when your assistant can run shell commands. Add another option only for a need the first cannot cover. Memory links open the AIDD templates for the corresponding files in your project's `aidd_docs/memory/`. -#### Version control +#### πŸ”€ Version control > Work with repositories, pull requests and CI runs. Project conventions: [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). @@ -24,7 +24,7 @@ Memory links open the AIDD templates for the corresponding files in your project | GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | | Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | -#### Ticketing +#### 🎫 Ticketing > Find, create and update tickets. Team workflow: [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). @@ -34,7 +34,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | | Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | -#### Documentation and workspace +#### πŸ“š Documentation and workspace > Access team documents, files, email and calendars. Connected tools: [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). @@ -44,7 +44,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | | Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | -#### Browser +#### 🌐 Browser > Open the application and check its behavior in a browser. Test instructions: [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). @@ -54,7 +54,7 @@ Memory links open the AIDD templates for the corresponding files in your project | Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | | Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | -#### Design +#### 🎨 Design > Read designs and follow the project's design system. UI guidelines: [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). @@ -62,7 +62,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | -#### Monitoring +#### 🚨 Monitoring > Read application errors and investigate failures. Monitoring configuration: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). @@ -70,7 +70,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | -#### Deployment +#### πŸš€ Deployment > Deploy the application and inspect deployment logs. Deployment instructions: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). @@ -78,7 +78,7 @@ Memory links open the AIDD templates for the corresponding files in your project | --- | --- | --- | | Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | -#### Database +#### πŸ—„οΈ Database > Explore the database and run migrations. Database conventions: [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). @@ -93,10 +93,10 @@ Add any other services your team uses to the relevant table. ### 2) πŸ”Œ Install and sign in 1. Check existing connections first; in [Claude Code](https://code.claude.com/docs/en/mcp#managing-your-servers), run `/mcp` to see MCP server status. -2. Open your tool's documentation from the table. -3. For a CLI, follow its installation and login instructions. -4. For MCP, follow the provider's instructions for your AI client, then authenticate. -5. Check the account, workspace and requested permissions before granting access. +2. Open the linked setup guide for your tool; for MCP, select your AI client. +3. Install the chosen CLI, server or plugin if it is not already available. +4. Check the intended account, workspace and requested permissions before granting access. +5. Authenticate using the provider's documented login method. **CLI example: GitHub.** Install `gh` using its [installation guide](https://github.com/cli/cli#installation), then run: From e1b2593fb676014777d9fe782536f80966de2856 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 17:07:56 +0800 Subject: [PATCH 13/16] feat(aidd-context): compare service access options and verify relevant memory --- .../skills/02-project-memory/SKILL.md | 5 +- .../actions/05-verify-connection.md | 24 ++- .../assets/connection-report.md | 10 +- .../assets/recipes/connect-services.md | 158 +++++++++++------- 4 files changed, 120 insertions(+), 77 deletions(-) diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index 78f705eb5..f031faf5a 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -12,8 +12,7 @@ flowchart LR update([refresh]) --> scan --> check --> write rewire([rewire]) --> sync verify([verify]) --> verify-connection - verify-connection -->|report| reported([connection report]) - verify-connection -->|memory missing| missing([memory missing]) + verify-connection --> reported([connection report]) scan -.-> empty([nothing to remember]) ``` @@ -31,7 +30,7 @@ Run the flow above, reading only the next action file. ## Transversal rules -- If a referenced file cannot be read, stop and say so. Never invent its content. +- Never invent unreadable content; setup, refresh and rewire stop when a referenced file cannot be read. - Ask before anything ambiguous. Never default silently. - A bank that already exists changes only through what the user approved, file by file and line by line. - End with a short report of what changed. diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md index 58cf3bba1..88ad75615 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -1,10 +1,10 @@ # 05 - Verify Connection -Check the assistant's service connections and fill the report. +Check project access and fill the report. ## Input -The bank in `aidd_docs/memory/`. +The project's bank in `aidd_docs/memory/` and the service-connection recipe. ## Output @@ -12,17 +12,15 @@ A printed report using [connection-report.md](../assets/connection-report.md). ## Process -1. **Read.** Read `ecosystem.md`, its referenced memory files and `testing.md` to identify required assistant access and targets. - - No memory bank: report it missing and stop. -2. **Check.** Use the available CLI, MCP or native tools to confirm the account and target, then perform one read per required service. - - Read browser content or database metadata where relevant. - - No writes, installs, login flows, configuration changes or secret output. +1. **Map.** Read the available `connect-services` recipe ([source](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md)) and the project memory relevant to its categories to identify required services, accounts and targets. + - **Coverage.** Include any other relevant memory files or services. + - **Missing memory.** Mark missing context as unverified, never as not needed. +2. **Check.** Inspect available CLI, MCP, native or API access and perform one read against each required account and target. + - **Failures.** Continue checking the other services when one fails. 3. **Report.** Fill `connection-report.md` from observed results, with one row per category. -## Test +## Rules -| Case | Pass | -| --- | --- | -| Report | all eight categories appear, with observed evidence or a missing access | -| Failed or unavailable read | no success is claimed; other services are still checked | -| Completion | no data, configuration or memory file changed | +- **Scope.** Check the assistant access the project requires; the catalogue is not an installation checklist. +- **Read-only.** No writes, installs, login flows, configuration or memory changes, or secret output. +- **Evidence.** A configured tool alone never proves access; report success only after a read matches the intended account and target. diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md index 538476632..49f78d4b7 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -1,6 +1,14 @@ # Connection Report - + | Category | Tool / target | Status | Evidence / next step | | --- | --- | --- | --- | diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md index 0bee0ec9b..b0f07277a 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -1,16 +1,48 @@ # Connect your services -Choose a CLI, MCP server or native tool so your AI assistant can work with your team's services. +Choose CLI, MCP or direct API access so your AI assistant can work with your team's services. Each category points to the project memory that records how your team uses those services. This gives the assistant the right repository, workspace and conventions for its work. - +## CLI, MCP or API? + +Reuse an existing connection that covers your task. Otherwise: + +```mermaid +--- +title: Choose service access +--- +flowchart LR + task["Required task"] + cli{"Usable CLI?"} + command["CLI"] + mcp{"Usable MCP or native tool?"} + tools["MCP or native tool"] + api{"Usable documented API?"} + direct["Direct API or SDK"] + missing["No supported access"] + task --> cli + cli -- yes --> command + cli -- no --> mcp + mcp -- yes --> tools + mcp -- no --> api + api -- yes --> direct + api -- no --> missing +``` + +| Option | Advantages | Limits | +| --- | --- | --- | +| CLI | Repeatable commands; filter output before sending it to the assistant | Requires shell access; commands may not cover your task | +| MCP | Tools callable directly by the assistant | Requires a compatible client; tool coverage and context cost vary | +| API / SDK | Direct access when CLI and MCP do not cover the operation | Requires network/runtime access; you handle authentication, pagination and errors | + +Prefer CLI when it covers the task: [Playwright documents lower context use](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp). This is not universal: [Claude Code can load MCP tools on demand](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). ## Steps to connect your services ### 1) πŸ”Ž Choose the tool -Reuse existing connections. For each service your project uses, start with one option that covers your task. Prefer a CLI when your assistant can run shell commands. Add another option only for a need the first cannot cover. +For each service your project uses, choose an option that covers your task. Add another only for a need the first cannot cover. Memory links open the AIDD templates for the corresponding files in your project's `aidd_docs/memory/`. @@ -18,110 +50,116 @@ Memory links open the AIDD templates for the corresponding files in your project > Work with repositories, pull requests and CI runs. Project conventions: [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| GitHub | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | -| GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | -| Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| GitHub | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | [REST API](https://docs.github.com/en/rest) | +| GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | [REST API](https://docs.gitlab.com/api/rest/) | +| Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | [Cloud REST API](https://developer.atlassian.com/cloud/bitbucket/rest/) | #### 🎫 Ticketing > Find, create and update tickets. Team workflow: [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| GitHub Issues | [`gh issue`](https://cli.github.com/manual/gh_issue) | [GitHub MCP](https://github.com/github/github-mcp-server) | -| Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | -| Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| GitHub Issues | [`gh issue`](https://cli.github.com/manual/gh_issue) | [GitHub MCP](https://github.com/github/github-mcp-server) | [Issues API](https://docs.github.com/en/rest/issues) | +| Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) | +| Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | [GraphQL API](https://linear.app/developers/graphql) | #### πŸ“š Documentation and workspace > Access team documents, files, email and calendars. Connected tools: [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | -| Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | -| Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [Cloud REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/) | +| Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | [REST API](https://developers.notion.com/reference/intro) | +| Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | [Workspace APIs](https://developers.google.com/workspace/products) | #### 🌐 Browser > Open the application and check its behavior in a browser. Test instructions: [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | -| Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | -| Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | [Library API](https://playwright.dev/docs/api/class-playwright) | +| Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | β€” | +| Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | β€” | #### 🎨 Design > Read designs and follow the project's design system. UI guidelines: [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | [REST API](https://developers.figma.com/docs/rest-api/) | #### 🚨 Monitoring > Read application errors and investigate failures. Monitoring configuration: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | [Web API](https://docs.sentry.io/api/) | #### πŸš€ Deployment > Deploy the application and inspect deployment logs. Deployment instructions: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | [REST API](https://vercel.com/docs/rest-api) | #### πŸ—„οΈ Database > Explore the database and run migrations. Database conventions: [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). -| Service | CLI | MCP or native tool | -| --- | --- | --- | -| PostgreSQL | [`psql`](https://www.postgresql.org/docs/current/app-psql.html) | β€” | -| MongoDB | [`mongosh`](https://www.mongodb.com/docs/mongodb-shell/) | [MongoDB MCP](https://www.mongodb.com/docs/mcp-server/) | -| Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | +| Service | CLI | MCP or native tool | API / SDK | +| --- | --- | --- | --- | +| PostgreSQL | [`psql`](https://www.postgresql.org/docs/current/app-psql.html) | β€” | [libpq client API](https://www.postgresql.org/docs/current/libpq.html) | +| MongoDB | [`mongosh`](https://www.mongodb.com/docs/mongodb-shell/) | [MongoDB MCP](https://www.mongodb.com/docs/mcp-server/) | [Drivers](https://www.mongodb.com/docs/drivers/) | +| Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | [Data REST API](https://supabase.com/docs/guides/api) for database reads and writes | -Add any other services your team uses to the relevant table. +Add any other services your team uses to the relevant table. `β€”` means no option is listed here. ### 2) πŸ”Œ Install and sign in -1. Check existing connections first; in [Claude Code](https://code.claude.com/docs/en/mcp#managing-your-servers), run `/mcp` to see MCP server status. -2. Open the linked setup guide for your tool; for MCP, select your AI client. -3. Install the chosen CLI, server or plugin if it is not already available. -4. Check the intended account, workspace and requested permissions before granting access. -5. Authenticate using the provider's documented login method. +1. Check existing access; in [Claude Code](https://code.claude.com/docs/en/mcp#managing-your-servers), `/mcp` shows MCP server status. +2. Follow the linked guide for your chosen CLI, MCP or API and client; install only what is missing. +3. Review the account, workspace and requested permissions, then authenticate; use read-only access when you only need reads. -**CLI example: GitHub.** Install `gh` using its [installation guide](https://github.com/cli/cli#installation), then run: +- **CLI / GitHub.** Install `gh` from its [guide](https://github.com/cli/cli#installation), then sign in and inspect the account: -```bash -gh auth login -gh auth status -``` + ```bash + gh auth login + gh auth status + ``` -**MCP example: Figma in Claude Code.** Figma recommends its plugin: +- **MCP / Figma in Claude Code.** Install the recommended plugin: -```bash -claude plugin install figma@claude-plugins-official -``` + ```bash + claude plugin install figma@claude-plugins-official + ``` + + Start a new session, run `/mcp`, select Figma, then **Authenticate**; other clients use [Figma's setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). -Start a new Claude Code session, run `/mcp`, select Figma, then **Authenticate**. For another client, use [Figma's setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). +- **API / GitHub.** With a token configured as described in the [REST API quickstart](https://docs.github.com/en/rest/quickstart), read the account: -Use a read-only mode when you only need to read. Require confirmation for writes; if your client cannot enforce it, disable write tools or use provider-enforced read-only access. + ```bash + curl --fail --silent --show-error \ + -H "Authorization: Bearer $GITHUB_TOKEN" \ + https://api.github.com/user + ``` + +Require confirmation for writes; if your client cannot enforce it, disable write tools or use provider-enforced read-only access. ### 3) βœ… Check the connection -Ask your assistant to verify the connections declared in project memory: +Ask your assistant to verify project access using the [verification action](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md) and its [report table](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md): -```text -Verify this project's connections against aidd_docs/memory/. -Report one row per category. -``` +- Run this prompt after recording the services and targets in project memory: -To disconnect later, remove the integration from your client and revoke its access in the service's account settings. + ```text + Verify this project's connections against aidd_docs/memory/. + Report one row per category. + ``` From 6c4fa30b609d49944356977c229a63738ba9464f Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 19:09:12 +0800 Subject: [PATCH 14/16] docs(context): clarify connection references and report labels --- .../2026_10_14_connect-services/review.md | 49 +++++++++++++++++++ .../actions/05-verify-connection.md | 20 ++++---- .../assets/connection-report.md | 14 +++--- .../assets/recipes/connect-services.md | 6 +-- 4 files changed, 69 insertions(+), 20 deletions(-) create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md new file mode 100644 index 000000000..34dbdc77b --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md @@ -0,0 +1,49 @@ +# Review: Connect services + +- **Verdict**: approve +- **Diff**: `origin/next...HEAD` plus tracked working edits to the recipe, verification action and report +- **Axes run**: code, functional, relevancy +- **Date**: 2026-10-14 +- **Findings**: 0 critical, 0 warning, 0 minor; formal findings limited to concrete P0/P1 risks + +## Phases + +### Phase 1: Recipe and setup + +- [x] Rename recipe and update its references: `README.md:239`, `token-optimization.md:452`, new `connect-services.md` replaces `mcp-installation.md`. +- [x] Eight actual H4 category headings with emojis: `connect-services.md:49–113`. +- [x] Service tables expose linked CLI, MCP/native and API/SDK alternatives; unsupported Google CLI labeled: `connect-services.md:53–122`. +- [x] Explain memory mapping and link category memory templates: `connect-services.md:5`, `connect-services.md:47–115`. +- [x] Three actionable steps; installation checks existing access, follows documentation, then authenticates; code examples belong to bullets: `connect-services.md:43`, `connect-services.md:125–165`. +- [x] Bold introductory labels use a colon; ordinary bullets avoid unnecessary labels: `connect-services.md:131`, `connect-services.md:138`, `connect-services.md:147`. + +### Phase 2: Verification + +- [x] Public `verify` entry routes to `verify-connection`: `02-project-memory/SKILL.md:4`, `02-project-memory/SKILL.md:14–15`, `02-project-memory/SKILL.md:29`. +- [x] Resolve the local recipe and read it by relative path; relevant memory is not a fixed filename list: `05-verify-connection.md:7`, `05-verify-connection.md:15–17`. +- [x] Simple map, read and report process; rules replace a terminal Test section; unavailable context never means not needed: `05-verify-connection.md:15–26`. +- [x] Read-only operation excludes writes, installs, login, memory changes and secret output; successful reads must match account and target: `05-verify-connection.md:25–26`. +- [x] One category per four-column report; aggregate status preserves failed or unverified required access: `connection-report.md:4–24`. + +### Phase 3: Validator support + +- [x] CLI validation permits H4 subsections only below a direct numbered H3 step; malformed numbered headings still fail; unit cases cover valid subsections, orphans, changed parents and malformed headings: `recipe-validation.ts:397–439`, `recipe-validation.unit.test.ts:120–155`. + +## Findings + +None. + +## Verification + +| Metric | Value | +| --- | --- | +| Verified | 100% (12/12) static acceptance criteria reviewed | +| Files checked | All 10 changed PR files: README, recipe validator, validator unit tests, context CATALOG, project-memory router, verification action, connection report, new connect-services recipe, deleted mcp-installation recipe, token-optimization recipe; three current tracked doc edits included | +| Static check | `git diff --check origin/next` exited 0; scoped README/plugins/CLI search found no old `mcp-installation` reference | +| Unchecked | Provider execution and runtime test results: not-applicable to this read-only static review; provider documentation contents and link availability not independently rechecked | +| Unplanned | None; validator relaxation directly supports requested H4 category structure | +| Completion score | 100: every supplied criterion examined | +| Quality score | 92: criteria statically fulfilled; small duplication and local catalogue resolution indirection remain; runtime/provider behavior is not established by this review | +| Non-blocking simplification | `connect-services.md:9–39`: graph shows a decision sequence, table shows tradeoffs; their functions differ, but graph repeats CLI preference and API fallback. Retaining just the comparison table and a short selection sentence would reduce page length without losing useful choice information | +| Non-blocking clarity | `05-verify-connection.md:15`: local recipe resolution has an existing authoritative location policy at `../../12-cook/references/recipe-locations.md`; linking that policy would remove ambiguity without duplicating it | +| Non-blocking router consistency | `02-project-memory/SKILL.md:36`: β€œreport of what changed” predates the read-only verify entry; scoping it to setup/refresh/rewire would align it with verify's observed-results report | diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md index 88ad75615..b4eeee682 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md @@ -4,7 +4,7 @@ Check project access and fill the report. ## Input -The project's bank in `aidd_docs/memory/` and the service-connection recipe. +The project's bank in `aidd_docs/memory/` and the local `connect-services.md` recipe. ## Output @@ -12,15 +12,15 @@ A printed report using [connection-report.md](../assets/connection-report.md). ## Process -1. **Map.** Read the available `connect-services` recipe ([source](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md)) and the project memory relevant to its categories to identify required services, accounts and targets. - - **Coverage.** Include any other relevant memory files or services. - - **Missing memory.** Mark missing context as unverified, never as not needed. -2. **Check.** Inspect available CLI, MCP, native or API access and perform one read against each required account and target. - - **Failures.** Continue checking the other services when one fails. -3. **Report.** Fill `connection-report.md` from observed results, with one row per category. +1. **Map**: Resolve `connect-services.md` from the local recipe catalogue, then read it by its relative path and read the relevant project memory to identify required services, accounts and targets. + - Include any other relevant memory files or services. + - Mark missing context as unverified, never as not needed. +2. **Check**: Inspect available CLI, MCP, native or API access and perform one read against each required account and target. + - Continue checking the other services when one fails. +3. **Report**: Fill `connection-report.md` from observed results, with one row per category. ## Rules -- **Scope.** Check the assistant access the project requires; the catalogue is not an installation checklist. -- **Read-only.** No writes, installs, login flows, configuration or memory changes, or secret output. -- **Evidence.** A configured tool alone never proves access; report success only after a read matches the intended account and target. +- Check the assistant access the project requires; the catalogue is not an installation checklist. +- No writes, installs, login flows, configuration or memory changes, or secret output. +- A configured tool alone never proves access; report success only after a read matches the intended account and target. diff --git a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md index 49f78d4b7..a19b75744 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md @@ -1,13 +1,13 @@ # Connection Report | Category | Tool / target | Status | Evidence / next step | diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md index b0f07277a..d0850de09 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -128,14 +128,14 @@ Add any other services your team uses to the relevant table. `β€”` means no opti 2. Follow the linked guide for your chosen CLI, MCP or API and client; install only what is missing. 3. Review the account, workspace and requested permissions, then authenticate; use read-only access when you only need reads. -- **CLI / GitHub.** Install `gh` from its [guide](https://github.com/cli/cli#installation), then sign in and inspect the account: +- **CLI / GitHub**: Install `gh` from its [guide](https://github.com/cli/cli#installation), then sign in and inspect the account: ```bash gh auth login gh auth status ``` -- **MCP / Figma in Claude Code.** Install the recommended plugin: +- **MCP / Figma in Claude Code**: Install the recommended plugin: ```bash claude plugin install figma@claude-plugins-official @@ -143,7 +143,7 @@ Add any other services your team uses to the relevant table. `β€”` means no opti Start a new session, run `/mcp`, select Figma, then **Authenticate**; other clients use [Figma's setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). -- **API / GitHub.** With a token configured as described in the [REST API quickstart](https://docs.github.com/en/rest/quickstart), read the account: +- **API / GitHub**: With a token configured as described in the [REST API quickstart](https://docs.github.com/en/rest/quickstart), read the account: ```bash curl --fail --silent --show-error \ From 13ccbef45cf3ba26e6b03c87fbc8af7ef3bea3e3 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 21:39:50 +0800 Subject: [PATCH 15/16] docs(context): explain service access use cases --- .../assets/recipes/connect-services.md | 38 +++++-------------- 1 file changed, 9 insertions(+), 29 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md index d0850de09..adad19a08 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -6,35 +6,13 @@ Each category points to the project memory that records how your team uses those ## CLI, MCP or API? -Reuse an existing connection that covers your task. Otherwise: - -```mermaid ---- -title: Choose service access ---- -flowchart LR - task["Required task"] - cli{"Usable CLI?"} - command["CLI"] - mcp{"Usable MCP or native tool?"} - tools["MCP or native tool"] - api{"Usable documented API?"} - direct["Direct API or SDK"] - missing["No supported access"] - task --> cli - cli -- yes --> command - cli -- no --> mcp - mcp -- yes --> tools - mcp -- no --> api - api -- yes --> direct - api -- no --> missing -``` - -| Option | Advantages | Limits | -| --- | --- | --- | -| CLI | Repeatable commands; filter output before sending it to the assistant | Requires shell access; commands may not cover your task | -| MCP | Tools callable directly by the assistant | Requires a compatible client; tool coverage and context cost vary | -| API / SDK | Direct access when CLI and MCP do not cover the operation | Requires network/runtime access; you handle authentication, pagination and errors | +Reuse an existing connection that covers your task. Choose by the operation you need: + +| Option | When to use it | Advantages | Limits | +| --- | --- | --- | --- | +| CLI | Repeatable commands: inspect CI runs, manage pull requests or run migrations | Scriptable; filter output before sending it to the assistant | Requires shell access; commands may not cover your task | +| MCP | Interactive assistant work: explore a workspace, read design context or query tickets through available tools | Tools callable directly by the assistant | Requires a compatible client; tool coverage and context cost vary | +| API / SDK | A specific operation is missing from CLI and MCP, or you need custom queries and batch processing | Control requests and returned data | Requires network/runtime access; you handle authentication, pagination and errors | Prefer CLI when it covers the task: [Playwright documents lower context use](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp). This is not universal: [Claude Code can load MCP tools on demand](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). @@ -128,6 +106,8 @@ Add any other services your team uses to the relevant table. `β€”` means no opti 2. Follow the linked guide for your chosen CLI, MCP or API and client; install only what is missing. 3. Review the account, workspace and requested permissions, then authenticate; use read-only access when you only need reads. +These are setup examples, not required installations. Follow the guide for your service and client. + - **CLI / GitHub**: Install `gh` from its [guide](https://github.com/cli/cli#installation), then sign in and inspect the account: ```bash From ad4b83258a9d92e81dd7edd12949f6b124dee17d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 22:51:17 +0800 Subject: [PATCH 16/16] docs(context): refine service access comparison --- .../2026_10_14_connect-services/challenge.md | 21 +++++ .../assets/recipes/connect-services.md | 94 ++++++++++--------- 2 files changed, 69 insertions(+), 46 deletions(-) create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md new file mode 100644 index 000000000..188891b1a --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md @@ -0,0 +1,21 @@ +**Verdict:** READY +**Scope:** Final connect-services recipe against the agreed concise service-setup guide. +**Evidence limits:** Static documentation review; provider authentication and reads were not exercised. Sources checked 2026-10-14. + +## Verified + +- **Choice:** Four options compare use cases, advantages and limits; category tables retain CLI and MCP/native alternatives. +- **Accuracy:** Context savings are conditional, matching [Playwright](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp) and [Claude Code's deferred tools](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). No universal speed or freshness claim remains. +- **Setup:** Commands are labeled examples. The Figma command matches its [official setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). Reusable API access points to Generate Skill. Its cross-skill link uses the source URL so installation does not break it. +- **Verification:** Existing action maps relevant memory, performs target-specific reads and fills the category report without changing services. +- **Checks:** Architecture rules pass; local Markdown links have no broken target; all three bundled recipes validate; diff whitespace check passes. + +## Blockers + +None. + +## Suggestions + +| Finding | Evidence | Minimal improvement | +| --- | --- | --- | +| API and SDK are different layers, though both are useful choices for this guide | [Octokit wraps GitHub APIs](https://github.com/octokit/octokit.js), checked 2026-10-14 | Optionally say β€œAn SDK can wrap an API”; current use-case distinction is sufficient | diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md index adad19a08..50066b5be 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md @@ -1,20 +1,23 @@ # Connect your services -Choose CLI, MCP or direct API access so your AI assistant can work with your team's services. +Connect CLI, MCP, API or SDK access so your AI assistant can work with your team's services. -Each category points to the project memory that records how your team uses those services. This gives the assistant the right repository, workspace and conventions for its work. +**Each category points to the project memory that records how your team uses those services.** -## CLI, MCP or API? +> This gives the assistant the right repository, workspace and conventions for its work. -Reuse an existing connection that covers your task. Choose by the operation you need: +## CLI, MCP, API or SDK? -| Option | When to use it | Advantages | Limits | +Reuse an existing connection that covers your task. Prefer CLI when it covers the task and follows official recommendations. + +| πŸ”Œ Option | 🎯 When to use it | βœ… Advantages | ⚠️ Limits | | --- | --- | --- | --- | -| CLI | Repeatable commands: inspect CI runs, manage pull requests or run migrations | Scriptable; filter output before sending it to the assistant | Requires shell access; commands may not cover your task | -| MCP | Interactive assistant work: explore a workspace, read design context or query tickets through available tools | Tools callable directly by the assistant | Requires a compatible client; tool coverage and context cost vary | -| API / SDK | A specific operation is missing from CLI and MCP, or you need custom queries and batch processing | Control requests and returned data | Requires network/runtime access; you handle authentication, pagination and errors | +| CLI | Repeatable tasks with shell access | Scriptable; filter output; can reduce context overhead | Commands vary by version; check installed `--help`; coverage may be incomplete | +| MCP | Direct assistant interaction | Structured inputs; discoverable tools; simple invocation | Client compatibility; tool and output context cost; [server trust and permissions](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) | +| [API](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api) | Operations missing from existing tools | Control requests, filters and returned data | Handle authentication, pagination, rate limits and errors | +| [SDK](https://github.com/octokit/octokit.js) | Reusable integrations in code | Language-native calls; less request boilerplate | Dependencies and version compatibility; coverage varies by library | -Prefer CLI when it covers the task: [Playwright documents lower context use](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp). This is not universal: [Claude Code can load MCP tools on demand](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). +[Playwright documents lower CLI context use](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp); [Claude Code can load MCP tools on demand](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). Speed and token cost depend on the tool and client. ## Steps to connect your services @@ -28,82 +31,82 @@ Memory links open the AIDD templates for the corresponding files in your project > Work with repositories, pull requests and CI runs. Project conventions: [vcs.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/vcs.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| GitHub | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | [REST API](https://docs.github.com/en/rest) | -| GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | [REST API](https://docs.gitlab.com/api/rest/) | -| Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | [Cloud REST API](https://developer.atlassian.com/cloud/bitbucket/rest/) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| GitHub | [`gh`](https://cli.github.com/manual/) | [GitHub MCP](https://github.com/github/github-mcp-server) | +| GitLab | [`glab`](https://docs.gitlab.com/cli/) | [GitLab MCP](https://docs.gitlab.com/user/model_context_protocol/mcp_server/) | +| Bitbucket | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) for search and read access | #### 🎫 Ticketing > Find, create and update tickets. Team workflow: [backlog.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/backlog/backlog.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| GitHub Issues | [`gh issue`](https://cli.github.com/manual/gh_issue) | [GitHub MCP](https://github.com/github/github-mcp-server) | [Issues API](https://docs.github.com/en/rest/issues) | -| Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) | -| Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | [GraphQL API](https://linear.app/developers/graphql) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| GitHub Issues | [`gh issue`](https://cli.github.com/manual/gh_issue) | [GitHub MCP](https://github.com/github/github-mcp-server) | +| Jira Cloud | [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/jira/) | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Linear | β€” | [Linear MCP](https://linear.app/docs/mcp) | #### πŸ“š Documentation and workspace > Access team documents, files, email and calendars. Connected tools: [ecosystem.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ecosystem/ecosystem.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | [Cloud REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/) | -| Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | [REST API](https://developers.notion.com/reference/intro) | -| Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | [Workspace APIs](https://developers.google.com/workspace/products) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Confluence | β€” | [Atlassian Rovo MCP](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/) | +| Notion | [`ntn`](https://developers.notion.com/cli/get-started/overview) for API scripts | [Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp) | +| Google Workspace | [`gws`](https://github.com/googleworkspace/cli) ⚠️ Not officially supported by Google | β€” | #### 🌐 Browser > Open the application and check its behavior in a browser. Test instructions: [testing.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/testing.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | [Library API](https://playwright.dev/docs/api/class-playwright) | -| Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | β€” | -| Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | β€” | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Playwright | [`playwright-cli`](https://playwright.dev/agent-cli/installation); [`npx playwright test`](https://playwright.dev/docs/test-cli) for tests | [Playwright MCP](https://playwright.dev/docs/getting-started-mcp) | +| Claude in Chrome | β€” | [Chrome extension](https://support.claude.com/en/articles/12012173-get-started-with-claude-in-chrome) | +| Cursor Browser | β€” | [Built-in browser](https://cursor.com/docs/agent/tools/browser) | #### 🎨 Design > Read designs and follow the project's design system. UI guidelines: [design.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/design.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | [REST API](https://developers.figma.com/docs/rest-api/) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Figma | β€” | [Figma MCP](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | #### 🚨 Monitoring > Read application errors and investigate failures. Monitoring configuration: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | [Web API](https://docs.sentry.io/api/) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Sentry | [`sentry`](https://cli.sentry.dev/) | [Sentry MCP](https://mcp.sentry.dev/) | #### πŸš€ Deployment > Deploy the application and inspect deployment logs. Deployment instructions: [deployment.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/deployment/deployment.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | [REST API](https://vercel.com/docs/rest-api) | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| Vercel | [`vercel`](https://vercel.com/docs/cli) | [Vercel MCP](https://vercel.com/docs/agent-resources/vercel-mcp) | #### πŸ—„οΈ Database > Explore the database and run migrations. Database conventions: [database.md](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/database/database.md). -| Service | CLI | MCP or native tool | API / SDK | -| --- | --- | --- | --- | -| PostgreSQL | [`psql`](https://www.postgresql.org/docs/current/app-psql.html) | β€” | [libpq client API](https://www.postgresql.org/docs/current/libpq.html) | -| MongoDB | [`mongosh`](https://www.mongodb.com/docs/mongodb-shell/) | [MongoDB MCP](https://www.mongodb.com/docs/mcp-server/) | [Drivers](https://www.mongodb.com/docs/drivers/) | -| Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | [Data REST API](https://supabase.com/docs/guides/api) for database reads and writes | +| Service | CLI | MCP or native tool | +| --- | --- | --- | +| PostgreSQL | [`psql`](https://www.postgresql.org/docs/current/app-psql.html) | β€” | +| MongoDB | [`mongosh`](https://www.mongodb.com/docs/mongodb-shell/) | [MongoDB MCP](https://www.mongodb.com/docs/mcp-server/) | +| Supabase | [`supabase`](https://supabase.com/docs/reference/cli/introduction) for migrations and local development | [Supabase MCP](https://supabase.com/docs/guides/ai-tools/mcp) for exploration | Add any other services your team uses to the relevant table. `β€”` means no option is listed here. ### 2) πŸ”Œ Install and sign in 1. Check existing access; in [Claude Code](https://code.claude.com/docs/en/mcp#managing-your-servers), `/mcp` shows MCP server status. -2. Follow the linked guide for your chosen CLI, MCP or API and client; install only what is missing. +2. Follow the linked guide for your chosen option and client; install only what is missing. 3. Review the account, workspace and requested permissions, then authenticate; use read-only access when you only need reads. These are setup examples, not required installations. Follow the guide for your service and client. @@ -123,7 +126,7 @@ These are setup examples, not required installations. Follow the guide for your Start a new session, run `/mcp`, select Figma, then **Authenticate**; other clients use [Figma's setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). -- **API / GitHub**: With a token configured as described in the [REST API quickstart](https://docs.github.com/en/rest/quickstart), read the account: +- **API / GitHub**: Wrap reusable API access in a skill with `/aidd-context:04-skill-generate` ([Generate Skill](https://github.com/ai-driven-dev/framework/blob/next/plugins/aidd-context/skills/04-skill-generate/SKILL.md)). With a token configured as described in the [REST API quickstart](https://docs.github.com/en/rest/quickstart), read the account: ```bash curl --fail --silent --show-error \ @@ -141,5 +144,4 @@ Ask your assistant to verify project access using the [verification action](http ```text Verify this project's connections against aidd_docs/memory/. - Report one row per category. ```