From 17c5d84eb23b08db7916cc2a86eb1ad58abcb82b Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 12:53:35 +0800 Subject: [PATCH 01/32] 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 216fdbf210936c61dc957661346c98ae2e6a7af4 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:02:30 +0800 Subject: [PATCH 02/32] 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 d165f0f402f2980a31e763a00a6b8a3717410879 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:08:47 +0800 Subject: [PATCH 03/32] 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 c1b3c62f82428e1d6c0fa2103159533ea7bb4ff3 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:11:53 +0800 Subject: [PATCH 04/32] 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 106c8a9f2b5ef1946e8467f60bcb22f56ca55215 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:22:09 +0800 Subject: [PATCH 05/32] 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 176335539..888a1c349 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 6cc4fe1e5efe90259e98d0bdec7d64a16b35bc80 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:23:36 +0800 Subject: [PATCH 06/32] 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 4e458dded3630693b9c6a1382353047876e6c094 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 13:45:28 +0800 Subject: [PATCH 07/32] 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 35cc94a25888a0c4a823def2d4bcad40a8a1addb Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 15:54:50 +0800 Subject: [PATCH 08/32] 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 a34de6ca19906adeb73884135994eb8dbfc217fc Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 15:58:18 +0800 Subject: [PATCH 09/32] 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 16b2636cb2f3e49f331e4493130ec0b46df6b30e Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 16:03:32 +0800 Subject: [PATCH 10/32] 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 775ecd494826ee5675cc794bcc67b6ca27638dba Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 16:12:58 +0800 Subject: [PATCH 11/32] 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 e5496c38a..c40f1694d 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 fce411a6a432a3dfc35292fb5421cdf7d01e89a9 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 16:28:25 +0800 Subject: [PATCH 12/32] 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 fec08023447e000c0a7c7c5e8a03b42cc54b10ac Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 17:07:56 +0800 Subject: [PATCH 13/32] 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 07b5fc636454b99702bf3629932d1249633a3186 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 19:09:12 +0800 Subject: [PATCH 14/32] 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 64e3b33b3f34c36dd3543519be3133fe3b5683cb Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 21:39:50 +0800 Subject: [PATCH 15/32] 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 578facd208ff815dd37ca0a6e28e6a4b5f9dfd39 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 14 Oct 2026 22:51:17 +0800 Subject: [PATCH 16/32] 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. ``` From a201900c0995bde86d5deb2ef33bdbbb85ea52c8 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 20 Oct 2026 02:31:31 +0000 Subject: [PATCH 17/32] feat(aidd-context): check the assistant's service access from project memory --- README.md | 4 +- .../2026_10_14_connect-services/phase-1.md | 115 ++++++++++++++++++ .../2026_10_14_connect-services/phase-2.md | 57 +++++++++ .../2026_10_14_connect-services/phase-3.md | 78 ++++++++++++ .../2026_10_14_connect-services/phase-4.md | 77 ++++++++++++ .../2026_10_14_connect-services/plan.md | 42 +++++++ plugins/aidd-context/CATALOG.md | 9 ++ .../skills/13-access-check/SKILL.md | 28 +++++ .../13-access-check/actions/01-check.md | 48 ++++++++ .../13-access-check/assets/access-report.md | 15 +++ scripts/__tests__/architecture-rules.test.js | 2 +- 11 files changed, 472 insertions(+), 3 deletions(-) create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md create mode 100644 aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md create mode 100644 plugins/aidd-context/skills/13-access-check/SKILL.md create mode 100644 plugins/aidd-context/skills/13-access-check/actions/01-check.md create mode 100644 plugins/aidd-context/skills/13-access-check/assets/access-report.md diff --git a/README.md b/README.md index c40f1694d..894c97923 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Unify **engineering teams** around **standardized workflows** and **shared best 🧱 **IDE agnostic** Β· πŸ—οΈ **Legacy systems** Β· 🌱 **Token-optimized** Β· πŸ‡«πŸ‡· **Made in France**

- 9 plugins Β· 51 skills Β· 2 agents + 9 plugins Β· 52 skills Β· 2 agents

[![Open Source](https://img.shields.io/badge/Open_Source-Yes-yellow?logo=open-source-initiative&logoColor=white)](https://opensource.org/) @@ -248,7 +248,7 @@ Nine plugins covering the whole SDLC β€” **install the six stable ones**; they w ### 🧭 [aidd-context](plugins/aidd-context/README.md) -`13 skills` Β· stable +`14 skills` Β· stable Project init, memory bank, context-artifact generation, diagrams, learning, exploration. diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md new file mode 100644 index 000000000..fa927d14a --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md @@ -0,0 +1,115 @@ +--- +status: in-progress +--- + +# Instruction: Create the `13-access-check` skill + +## Architecture projection + +> Tree of the final files. βœ… create Β· ✏️ modify Β· ❌ delete + +```txt +. +β”œβ”€β”€ docs/ +β”‚ └── CATALOG.md ✏️ row for 13-access-check +└── plugins/aidd-context/ + β”œβ”€β”€ README.md ✏️ row for access-check + └── skills/13-access-check/ + β”œβ”€β”€ SKILL.md βœ… router, one action + β”œβ”€β”€ actions/ + β”‚ └── 01-check.md βœ… from 02-project-memory/actions/05-verify-connection.md + └── assets/ + └── access-report.md βœ… from 02-project-memory/assets/connection-report.md, one row per edge +``` + +## User Journey + +```mermaid +flowchart TD + A[/aidd-context:13-access-check/] --> B{aidd_docs/memory/ holds a .md?} + B -- no --> C[propose 02-project-memory setup, stop] + B -- yes --> D{ecosystem.md exists?} + D -- no --> E[propose 02-project-memory refresh, stop] + D -- yes --> F{any Agent edge?} + F -- no --> G[report nothing to check, stop] + F -- yes --> H[map each edge to tool, mode, account, target] + H --> I[probe one read per edge] + I --> J[print the access report] +``` + +## Test Scope + +```mermaid +--- +title: Test scope +--- +journey + section Setup + Project with memory and ecosystem.md holding Agent edges => bank ready: 5: system + section Happy path + Run the skill => one report row per Agent edge with tool, mode, account, target, status and evidence: 5: cli + Run the skill => no file under the project changed: 5: cli + section Edge case - no bank + aidd_docs/memory/ empty => run the skill => proposes 02-project-memory setup and stops: 1: cli + section Edge case - no ecosystem + bank without ecosystem.md => run the skill => proposes 02-project-memory refresh and stops: 1: cli + section Edge case - no Agent edge + ecosystem.md with App or Human edges only => run the skill => reports nothing to check: 1: cli + section Edge case - one access fails + one CLI not signed in => run the skill => that row is ❌ with one corrective action, other rows still probed: 1: cli + section Edge case - wrong target + authenticated on another account => run the skill => that row is ⚠️ naming expected and observed: 1: cli +``` + +## Tasks to do + +### `1)` Router + +> A skill whose name and description say what it checks and what it never does. + +1. `SKILL.md` frontmatter: `name: 13-access-check`, description "Check that the assistant can reach the services recorded in project memory, read-only. Use when the user wants to verify or diagnose service access. Not for installing or configuring services.", `argument-hint: tool`. +2. Flowchart of the journey above, one action `check`. +3. Transversal rules: read-only (no writes, installs, logins, configuration or memory changes); never print a secret; a configured tool never proves access, only a read matching the intended account and target does; continue past a failure. + +### `2)` Check action + +> Map the memory to accesses, probe each once, report. + +1. `## Input`: `aidd_docs/memory/ecosystem.md`, plus `vcs.md` and `backlog.md` for accounts and targets. No recipe. +2. `## Process`: **Require** (the three stop cases and their proposal), **Map** (one row per `Agent -- mode --> Tool` edge; an argument narrows to one tool), **Probe** (`cli` => a read-only command, `mcp` => a read tool, `http` => one authenticated GET with the token from the environment), **Report** (fill `access-report.md`). +3. Status per row: βœ… read matches account and target; ❌ read failed, with one corrective action; πŸ”Œ tool or server absent; ⚠️ authenticated but account or target different (naming expected and observed) or not recorded in memory (next step: record it in memory). `Human` and `App` edges get no row. +4. `## Test` table covering every case of the test scope. + +### `3)` Report asset + +> A report whose rows follow the project, not a fixed category list. + +1. Columns: Tool, Mode, Account / target, Status, Evidence / next step. +2. Keep the status legend from `connection-report.md`, drop ⏭️ (an edge in memory is never "not needed"). +3. Inline comment contract, removed from the printed report. + +### `4)` Listings + +> The skill is discoverable where skills are listed by hand. + +1. Add `13-access-check` to the aidd-context table of `docs/CATALOG.md` with action `01-check`. +2. Add the `access-check` row to `plugins/aidd-context/README.md`. + +### `5)` Onboard + +> A first setup ends with the assistant's access proven. + +1. `00-onboard` `zones.md`: a `service access` foundation after `memory wiring`, command `aidd-context:13-access-check`, met unless memory or wiring was set up this session and the check has not run or been skipped since. +2. Foundation counts follow: `flow.md`, `screen-map.md`, `03-present.md` test. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------------------------------------------------------------------------------------------- | +| 1 | the skill frontmatter passes the pre-commit skill frontmatter and argument-hint checks | +| 1 | no file of the skill links outside `13-access-check/` | +| 2 | each stop case names the exact command to run next and changes no file | +| 2 | a run against this repository lists the `gh` edges to GitHub and the Roadmap board, each with evidence | +| 3 | the report has one row per Agent edge and no category row | +| 4 | `docs/CATALOG.md` and the plugin README both list the skill; regenerated `CATALOG.md` and README counts show 14 aidd-context skills | +| 5 | an existing repo renders memory as step 1 of 3, and a session that found memory wired lists no access step | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md new file mode 100644 index 000000000..420a526a6 --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md @@ -0,0 +1,57 @@ +--- +status: pending +--- + +# Instruction: Restore `02-project-memory` to memory only + +## Architecture projection + +> Tree of the final files. βœ… create Β· ✏️ modify Β· ❌ delete + +```txt +. +└── plugins/aidd-context/skills/02-project-memory/ + β”œβ”€β”€ SKILL.md ✏️ back to origin/next + β”œβ”€β”€ actions/ + β”‚ └── 05-verify-connection.md ❌ moved to 13-access-check + └── assets/ + └── connection-report.md ❌ moved to 13-access-check +``` + +## User Journey + +```mermaid +flowchart TD + A[/aidd-context:02-project-memory/] --> B[setup, refresh or rewire] + B --> C[no verify entry offered] +``` + +## Test Scope + +```mermaid +--- +title: Test scope +--- +journey + section Happy path + Diff 02-project-memory against origin/next => no difference: 5: cli + Grep the repository for 05-verify-connection and connection-report.md => no match: 5: cli +``` + +## Tasks to do + +### `1)` Revert the skill + +> The memory skill does one thing again. + +1. Restore `02-project-memory/SKILL.md` from `origin/next`. +2. Delete `actions/05-verify-connection.md` and `assets/connection-report.md`. +3. Replace every remaining reference to them (recipe, task docs) with `/aidd-context:13-access-check`; the recipe ones land in phase 3. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------- | +| 1 | `02-project-memory/` is identical to `origin/next` | +| 1 | the argument hint is `setup \| refresh \| rewire` and the description names no verification | +| 1 | no file in the repository names `05-verify-connection` or `connection-report.md` | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md new file mode 100644 index 000000000..60f025dbd --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md @@ -0,0 +1,78 @@ +--- +status: pending +--- + +# Instruction: Apply the review to `connect-services.md` + +## Architecture projection + +> Tree of the final files. βœ… create Β· ✏️ modify Β· ❌ delete + +```txt +. +└── plugins/aidd-context/skills/12-cook/assets/recipes/ + └── connect-services.md ✏️ intro, step 2 examples, step 3 target +``` + +## User Journey + +```mermaid +flowchart TD + A[Read the recipe] --> B[record services in project memory] + B --> C[choose CLI, MCP, API or SDK per service] + C --> D[install and sign in, with the client's own MCP guide] + D --> E[/aidd-context:13-access-check/] +``` + +## Test Scope + +```mermaid +--- +title: Test scope +--- +journey + section Happy path + Validate bundled recipes => connect-services.md has no finding: 5: cli + Check markdown links => every link of the recipe resolves: 5: cli + Read step 2 => one example each for CLI, MCP, API and SDK: 5: cli + Read step 3 => it names /aidd-context:13-access-check and no 02-project-memory action: 5: cli +``` + +## Tasks to do + +### `1)` Intro + +> The reader records services in memory before connecting them (review #7). + +1. Add one line: project memory records which services the team uses, in `ecosystem.md`, built by `/aidd-context:02-project-memory`. + +### `2)` Step 2 examples + +> Four options announced, four shown, none contradicting CLI-first (review #3, #5, #6). + +1. Replace the GitHub API example with an internal team API: one `curl --fail` GET, token read from an environment variable, never pasted. +2. Add an SDK example called from application code (the `App` actor), one official client, a few lines. +3. One sentence: when a service has neither CLI nor MCP, run `/aidd-context:04-skill-generate` starting from its API. + +### `3)` Client coverage + +> Each client finds its own MCP setup without five copies of the same config (review #4). + +1. Keep the Claude Code `/mcp` example. +2. Add a table linking the official MCP setup page of Claude Code, Codex, Cursor, GitHub Copilot and OpenCode; fetch each URL before writing it. + +### `4)` Step 3 + +> Verification is one skill call. + +1. Replace the two links to `02-project-memory` files and the raw prompt with `/aidd-context:13-access-check`, by slash command, the way `start-a-project.md` names skills. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------------------------------------------------------------------------------- | +| 1 | the intro names `ecosystem.md` and `/aidd-context:02-project-memory` | +| 2 | no API or SDK example targets a service whose CLI the recipe already lists | +| 2 | no example prints or embeds a token value | +| 3 | the client table has five rows, each URL answering 200 on the day it was written | +| 4 | step 3 contains `/aidd-context:13-access-check` and no link into `02-project-memory/` | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md new file mode 100644 index 000000000..8b1143f37 --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md @@ -0,0 +1,77 @@ +--- +status: pending +--- + +# Instruction: Record the change and prove it end to end + +## Architecture projection + +> Tree of the final files. βœ… create Β· ✏️ modify Β· ❌ delete + +```txt +. +└── aidd_docs/tasks/2026_10/2026_10_14_connect-services/ + β”œβ”€β”€ challenge.md ✏️ verdict on the new scope + └── review.md ✏️ phase 2 is the new skill, not a 02-project-memory action +``` + +## User Journey + +```mermaid +flowchart TD + A[Reviewer opens the PR] --> B[reads challenge.md and review.md] + B --> C[sees each review finding and where it was resolved] +``` + +## Test Scope + +```mermaid +--- +title: Test scope +--- +journey + section Happy path + Run the pre-commit gate => green, CATALOG.md and README counts regenerated: 5: cli + Run the scripts tests => green: 5: cli + Run the CLI suite => green, H4 validator tests included: 5: cli + Run git diff --check against origin/next => no whitespace error: 5: cli + Run /aidd-context:13-access-check on this repository => report rows for the gh edges with evidence: 5: cli + section Edge case - empty bank + Temporary copy without aidd_docs/memory/ => run the skill => proposes 02-project-memory setup: 1: cli + section Teardown + Delete the temporary copy => repository unchanged: 5: system +``` + +## Tasks to do + +### `1)` Task records + +> The PR explains itself. + +1. `challenge.md`: scope, verdict and evidence for the extracted skill. +2. `review.md`: replace the 02-project-memory phase with the new skill; map each review finding (#1 to #11) to its resolution. + +### `2)` Gates + +> Every assertion green. + +1. `pnpm exec lefthook run pre-commit`. +2. `node --test 'scripts/__tests__/*.test.js'`. +3. `cd cli && pnpm test`. +4. `git diff --check origin/next`. + +### `3)` Live run + +> The skill does what its `## Test` claims. + +1. Run the skill on this repository and keep the printed report. +2. Run it on a temporary copy without memory and keep the stop message. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ----------------------------------------------------------------------------------- | +| 1 | each of the eleven review findings appears in `review.md` with its resolution | +| 2 | every gate exits 0 | +| 3 | the live report has one row per Agent edge of `aidd_docs/memory/ecosystem.md` | +| 3 | the empty-bank run proposes `/aidd-context:02-project-memory` and writes nothing | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md new file mode 100644 index 000000000..45bcc4bfc --- /dev/null +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md @@ -0,0 +1,42 @@ +--- +objective: "Service access verification lives in its own read-only aidd-context skill driven by project memory, 02-project-memory is back to memory only, and connect-services.md addresses the PR #1026 review." +status: in-progress +--- + +# Plan: Move service access verification into `aidd-context:13-access-check` + +## Overview + +| Field | Value | +| ---------- | ------------------------------------------------------------------------------------------------------- | +| **Goal** | Extract `verify` from `02-project-memory` into a dedicated skill and apply the review findings on the recipe | +| **Source** | PR #1026 (`ad4b8325`) and blafourcade's review of 2026-10-15 | + +## Phases + +| # | Phase | File | +| --- | --------------------------------------- | ---------------------------- | +| 1 | Create the `13-access-check` skill | [`phase-1.md`](./phase-1.md) | +| 2 | Restore `02-project-memory` to memory only | [`phase-2.md`](./phase-2.md) | +| 3 | Apply the review to `connect-services.md` | [`phase-3.md`](./phase-3.md) | +| 4 | Record the change and prove it end to end | [`phase-4.md`](./phase-4.md) | + +## Resources + +| Source | Verified | +| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| https://github.com/ai-driven-dev/framework/pull/1026 | review findings: scope too wide, relative path, API/SDK examples, client coverage, error handling | + +## Decisions + +| Decision | Why | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | +| A dedicated skill `13-access-check` in `aidd-context`, not an action of `02-project-memory` or `12-cook` | memory is about knowing the project, access is about reaching it; read-only probes producing a report stay on the knowledge side of the firewall (`docs/ARCHITECTURE.md`) | +| The services to check come from `ecosystem.md` edges `Agent -- mode --> Tool`, never from the recipe | a skill never links outside itself (`docs/ARCHITECTURE.md`); the edges already name each access and its mode, so no second taxonomy drifts | +| No memory => propose `/aidd-context:02-project-memory`, never run it | the check stays read-only and never invents a service list | +| The H4 recipe validator stays in this PR | `connect-services.md` nests `#### πŸ”€ Version control` under the direct step `### 1)`, which the validator rejects without it | +| Only `Agent` edges are checked; `Human` and `App` edges are ignored | the skill can only prove the assistant's own access; a human's login or the app's runtime token are not the assistant's to probe | +| A successful read with no expected account or target in memory is ⚠️, next step: record it in memory | success is claimed only against a known account and target; the next step turns ⚠️ into βœ… on the next run | +| Review #6: the recipe recommends running `/aidd-context:04-skill-generate` from the service's API | confirmed by the PR author on 2026-10-20 | +| Delivered as commits on the PR #1026 branch; no reply posted to the review | the PR author's choice | +| `00-onboard` offers the access check as the last foundation, only right after memory is set up or wired in the session | asked by the PR author on 2026-10-20; scoping it to the setup session keeps it from blocking every later session | diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 888a1c349..d55838e06 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -22,6 +22,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`skills/10-learn`](#skills10-learn) - [`skills/11-explore`](#skills11-explore) - [`skills/12-cook`](#skills12-cook) + - [`skills/13-access-check`](#skills13-access-check) --- @@ -220,3 +221,11 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - | | `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manages project recipes and practical guides. Use when the user wants to find a recipe, document a technique, research improvements, follow an existing guide, or check that its steps are usable.` | +#### `skills/13-access-check` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-check.md](skills/13-access-check/actions/01-check.md) | - | +| `assets` | [access-report.md](skills/13-access-check/assets/access-report.md) | - | +| `-` | [SKILL.md](skills/13-access-check/SKILL.md) | `Check that the assistant can reach the services recorded in project memory, read-only. Use when the user wants to verify or diagnose service access. Not for installing or configuring services.` | + diff --git a/plugins/aidd-context/skills/13-access-check/SKILL.md b/plugins/aidd-context/skills/13-access-check/SKILL.md new file mode 100644 index 000000000..872e457e3 --- /dev/null +++ b/plugins/aidd-context/skills/13-access-check/SKILL.md @@ -0,0 +1,28 @@ +--- +name: 13-access-check +description: Check that the assistant can reach the services recorded in project memory, read-only. Use when the user wants to verify or diagnose service access. Not for installing or configuring services. +argument-hint: tool +--- + +# Access Check + +```mermaid +flowchart LR + start([no argument, or a tool]) --> check --> reported([access report]) + check -.-> stopped([no memory, or nothing to check]) +``` + +## Actions + +Run the flow above, reading the action file first. + +| Action | Does | +| ------ | -------------------------------------------- | +| check | probe each access in memory, print the report | + +## Transversal rules + +- Read-only: no writes, installs, login flows, configuration or memory changes. +- Never print a secret, a token or a credential file's content. +- A configured tool never proves access. Only a read matching the intended account and target does. +- One access failing never stops the others. diff --git a/plugins/aidd-context/skills/13-access-check/actions/01-check.md b/plugins/aidd-context/skills/13-access-check/actions/01-check.md new file mode 100644 index 000000000..b42b47143 --- /dev/null +++ b/plugins/aidd-context/skills/13-access-check/actions/01-check.md @@ -0,0 +1,48 @@ +# 01 - Check + +Probe each access the project memory records for the assistant, then fill the report. + +## Input + +- `aidd_docs/memory/ecosystem.md`: the services and how each actor reaches them. +- `aidd_docs/memory/vcs.md` and `aidd_docs/memory/backlog.md`, when present: the expected accounts and targets. +- Optionally, one tool name, to check that tool only. + +## Output + +A printed report from [access-report.md](../assets/access-report.md), or one stop message. No file written. + +## Process + +1. **Require.** Stop on the first case that holds, with its message: + - `aidd_docs/memory/` holds no `.md`: propose `/aidd-context:02-project-memory` to set up the memory. + - No `ecosystem.md`: propose `/aidd-context:02-project-memory refresh` to add it. + - No `Agent` edge in `ecosystem.md`: report that nothing is for the assistant to check. +2. **Map.** One row per `Agent -- --> ` edge. + - `Human` and `App` edges get no row: their access is not the assistant's. + - Take the expected account and target from the memory, never from the tool itself. + - A tool argument keeps its rows only; an unknown tool stops with the tools the memory lists. +3. **Probe.** One read per row, proving both the account and the target. + - `cli`: a read-only command, such as an auth status, then a read on the target. + - `mcp`: a read tool of that server. + - `http`: one authenticated `GET`, the token taken from the environment. + - `web`: the assistant's browser tool, when it has one. +4. **Report.** Fill the report, one status per row: + - βœ… the read matches the expected account and target. + - ❌ the read failed: name one corrective action, then probe the next row. + - πŸ”Œ the command, server or browser tool is absent. + - ⚠️ the read worked on another account or target, naming both; or memory records none, next step: record it in memory. + +## Test + +| Case | Pass | +| --- | --- | +| Empty bank | proposes `/aidd-context:02-project-memory`, stops | +| No `ecosystem.md` | proposes `/aidd-context:02-project-memory refresh`, stops | +| `Human` and `App` edges only | reports nothing to check, stops | +| Report | one row per `Agent` edge, no row for `Human` or `App` | +| One access fails | its row is ❌ with one corrective action, the next rows still probed | +| Another account | its row is ⚠️, naming expected and observed | +| No expected account in memory | its row is ⚠️, next step: record it in memory | +| Tool argument | only that tool's rows | +| Every run | no file under the project changed, no secret printed | diff --git a/plugins/aidd-context/skills/13-access-check/assets/access-report.md b/plugins/aidd-context/skills/13-access-check/assets/access-report.md new file mode 100644 index 000000000..ff0008b84 --- /dev/null +++ b/plugins/aidd-context/skills/13-access-check/assets/access-report.md @@ -0,0 +1,15 @@ +# Access Report + + + +| Tool | Mode | Account / target | Status | Evidence / next step | +| --- | --- | --- | --- | --- | +| | | | | | + +βœ… Read matched Β· ❌ Read failed Β· πŸ”Œ Not configured Β· ⚠️ Unverified diff --git a/scripts/__tests__/architecture-rules.test.js b/scripts/__tests__/architecture-rules.test.js index 80de3f65e..35d0a1ad9 100644 --- a/scripts/__tests__/architecture-rules.test.js +++ b/scripts/__tests__/architecture-rules.test.js @@ -229,7 +229,7 @@ test("sweeping the repository's own plugins/ tree yields zero violations", () => assert.deepEqual(violations, []); // A sweep that never actually exercised a skill with action files would pass the same way β€” // this pins the sweep to the measured count so it cannot go vacuously green. - assert.equal(skillsWithActions, 48); + assert.equal(skillsWithActions, 49); }); test("a table that declares no action column cites nothing, whatever its cells read", () => { From d495f99a7b9a4e69aad58d0f9db166f3a96a2b88 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 20 Oct 2026 02:31:38 +0000 Subject: [PATCH 18/32] docs(aidd-context): list the access check skill --- docs/CATALOG.md | 1 + plugins/aidd-context/README.md | 3 ++- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/CATALOG.md b/docs/CATALOG.md index ece5b41c7..fb067640f 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -33,6 +33,7 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex | `10-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-gather`, `02-assess`, `03-write`, `04-sync` | | `11-explore` | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill` | | `12-cook` | Manage and validate technical project or bundled recipes | `01-list`, `02-upsert`, `03-research`, `04-apply`, `05-validate` | +| `13-access-check` | Check, read-only, that the assistant reaches the services in project memory | `01-check` | ## πŸ’» aidd-dev diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index 8b723c276..2550dba61 100644 --- a/plugins/aidd-context/README.md +++ b/plugins/aidd-context/README.md @@ -8,7 +8,7 @@ Knowledge production plugin for the AI-Driven Development framework. First time? Install with `/plugin install aidd-context@aidd-framework`, then run `aidd-context:00-onboard`. -Covers project bootstrap, the project memory bank, generation of context artifacts (skills, agents, rules, commands, hooks), Mermaid diagrams, learning, project exploration, recipes, and a plain-language onboarding guide. +Covers project bootstrap, the project memory bank, generation of context artifacts (skills, agents, rules, commands, hooks), Mermaid diagrams, learning, project exploration, recipes, a read-only service access check, and a plain-language onboarding guide. ## Skills @@ -22,6 +22,7 @@ Covers project bootstrap, the project memory bank, generation of context artifac | [1.5] | [learn](skills/10-learn/SKILL.md) | Capture durable learnings from the conversation or git history, score each, and route the worthwhile ones to memory, a decision record, a rule, or a new skill. | | [1.6] | [explore](skills/11-explore/SKILL.md) | Survey the project across three axes (tooling, context, codebase), then drill into one axis and point to the best-matching item for a goal. | | [1.7] | [cook](skills/12-cook/SKILL.md) | Maintain project and bundled recipes: list, research, create/update, apply, or validate one or all. | +| [1.8] | [access-check](skills/13-access-check/SKILL.md) | Check, read-only, that the assistant reaches each service the project memory records, and report what to fix. | ## Onboarding From 6f3e0e1f727c27ca8c4d25e48fb832992107c6d0 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 20 Oct 2026 02:31:38 +0000 Subject: [PATCH 19/32] feat(aidd-context): end onboarding foundations with the access check --- .../tasks/2026_10/2026_10_14_connect-services/phase-1.md | 2 +- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 3 ++- plugins/aidd-context/skills/00-onboard/assets/report.md | 1 + plugins/aidd-context/skills/00-onboard/references/flow.md | 4 ++-- .../skills/00-onboard/references/order/screen-map.md | 4 ++-- .../aidd-context/skills/00-onboard/references/state/zones.md | 4 +++- 6 files changed, 11 insertions(+), 7 deletions(-) diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md index fa927d14a..eed8e972d 100644 --- a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-1.md @@ -1,5 +1,5 @@ --- -status: in-progress +status: done --- # Instruction: Create the `13-access-check` skill diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index ec479950e..373b4e151 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -32,7 +32,8 @@ The rendered screen, and the user's reply. ## Test - The framing line shows on the first report of the session only. -- An existing repo renders memory as step 1 of 2. +- An existing repo renders memory as step 1 of 3. +- A session that found memory wired lists no access step. - A greenfield repo renders the stack first. - The banner shows on entry screens only. - Every `⚠️` carries a keyed fix. diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index e100e2b7c..ab8cbbba2 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -12,6 +12,7 @@ Your AIDD setup: Plugins βœ… Tech stack <βœ… established | ❌ not chosen yet> Memory + Access <βœ… checked | ❌ not checked yet; line dropped when memory was wired before this session> diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md index 88a9eb697..af9b23370 100644 --- a/plugins/aidd-context/skills/00-onboard/references/flow.md +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -2,8 +2,8 @@ ## Foundations (state-aware) -- Existing (code present): memory first, stack skipped. `project memory` β†’ `connect to the AI`. -- Greenfield (empty): `design tech stack` β†’ `project memory` β†’ `connect to the AI`. +- Existing (code present): memory first, stack skipped. `project memory` β†’ `connect to the AI` β†’ `check service access`. +- Greenfield (empty): `design tech stack` β†’ `project memory` β†’ `connect to the AI` β†’ `check service access`. ## Feature flow β€” 8 steps diff --git a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md index 0637cff48..7411ee41d 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -2,8 +2,8 @@ | State class | When | Screen | | ----------- | ---------------------------- | --------------------------------------------------- | -| greenfield | no code, no memory | welcome + foundations, stack first (3 steps) | -| existing | code present, memory missing | welcome + foundations, memory first (2 steps) | +| greenfield | no code, no memory | welcome + foundations, stack first (4 steps) | +| existing | code present, memory missing | welcome + foundations, memory first (3 steps) | | drift | a foundation is ⚠ | welcome + the warning-with-fix | | midwork | a dev-flow step pending | where-you-are on the flow + the next step | | idle | all clear | welcome + the flow (walk or SDLC), or the idle menu | diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md index ead0a597b..36b06770c 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/zones.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -4,16 +4,18 @@ Disk/VCS checks that place the project. Each check is met, drift (present, off c ## Foundations -State-aware order: existing repo (code) => memory first, stack skipped. Greenfield => stack β†’ memory β†’ wire. +State-aware order: existing repo (code) => memory first, stack skipped. Greenfield => stack β†’ memory β†’ wire β†’ access. | Check | Met when | Drift when | Deliverable | Command | | -------------- | ------------------------------------------------------------- | ------------------------ | -------------------------- | -------------------------------- | | tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | β€” | tech stack | `aidd-context:01-bootstrap` | | project memory | `aidd_docs/memory/` has real content | files empty/placeholder | project knowledge saved | `aidd-context:02-project-memory` | | memory wiring | the standard project memory block in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | +| service access | memory and wiring were met before this session, or the check ran or was skipped since they were set up | β€” | services reached by the AI | `aidd-context:13-access-check` | - tech stack missing only on greenfield (no code AND no synced memory). - memory wiring: no block or no context file = missing. Drift = a block present but not the standard one that imports the memory files. +- service access: the ledger decides, never a probe at scan. A bank set up in an earlier session never brings it back. ## Dev flow From 1fe57bf32d83f7fdd0f60a042083fc5bcad7d385 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 20 Oct 2026 02:31:54 +0000 Subject: [PATCH 20/32] refactor(aidd-context): keep project memory about memory only --- .../2026_10_14_connect-services/phase-2.md | 2 +- plugins/aidd-context/CATALOG.md | 4 +-- .../skills/02-project-memory/SKILL.md | 9 +++---- .../actions/05-verify-connection.md | 26 ------------------- .../assets/connection-report.md | 24 ----------------- 5 files changed, 5 insertions(+), 60 deletions(-) delete mode 100644 plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md delete mode 100644 plugins/aidd-context/skills/02-project-memory/assets/connection-report.md diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md index 420a526a6..0ca109f6e 100644 --- a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-2.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- # Instruction: Restore `02-project-memory` to memory only diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index d55838e06..bacd6f147 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -76,8 +76,6 @@ 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) | - | @@ -88,7 +86,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 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.` | +| `-` | [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.` | #### `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 f031faf5a..e854cb94b 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 | verify +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 --- # Project Memory @@ -11,8 +11,6 @@ flowchart LR new([no argument, or setup]) --> scan --> write --> sync --> wired([memory wired]) update([refresh]) --> scan --> check --> write rewire([rewire]) --> sync - verify([verify]) --> verify-connection - verify-connection --> reported([connection report]) scan -.-> empty([nothing to remember]) ``` @@ -26,11 +24,10 @@ 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 -- Never invent unreadable content; setup, refresh and rewire stop when a referenced file cannot be read. +- If a referenced file cannot be read, stop and say so. Never invent its content. - 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 deleted file mode 100644 index b4eeee682..000000000 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md +++ /dev/null @@ -1,26 +0,0 @@ -# 05 - Verify Connection - -Check project access and fill the report. - -## Input - -The project's bank in `aidd_docs/memory/` and the local `connect-services.md` recipe. - -## Output - -A printed report using [connection-report.md](../assets/connection-report.md). - -## Process - -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 - -- 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 deleted file mode 100644 index a19b75744..000000000 --- a/plugins/aidd-context/skills/02-project-memory/assets/connection-report.md +++ /dev/null @@ -1,24 +0,0 @@ -# Connection Report - - - -| Category | Tool / target | Status | Evidence / next step | -| --- | --- | --- | --- | -| Version control | | | | -| Ticketing | | | | -| Documentation and workspace | | | | -| Browser | | | | -| Design | | | | -| Monitoring | | | | -| Deployment | | | | -| Database | | | | - -βœ… All required reads passed Β· ❌ Read failed Β· πŸ”Œ Not configured Β· ⚠️ Unverified Β· ⏭️ Not needed From baa68e0610abf3a681ab88bbc24aa5864e5c9aa6 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 20 Oct 2026 02:33:39 +0000 Subject: [PATCH 21/32] docs(aidd-context): show all four access options and hand checks to access-check --- .../2026_10_14_connect-services/phase-3.md | 2 +- .../assets/recipes/connect-services.md | 37 ++++++++++++++----- 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md index 60f025dbd..4e7d11b50 100644 --- a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-3.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- # Instruction: Apply the review to `connect-services.md` 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 50066b5be..36424ffa3 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,6 +6,8 @@ Connect CLI, MCP, API or SDK access so your AI assistant can work with your team > This gives the assistant the right repository, workspace and conventions for its work. +Project memory records which services your team uses, and how, in `ecosystem.md`; `/aidd-context:02-project-memory` builds it. + ## CLI, MCP, API or SDK? Reuse an existing connection that covers your task. Prefer CLI when it covers the task and follows official recommendations. @@ -109,6 +111,16 @@ Add any other services your team uses to the relevant table. `β€”` means no opti 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. +Each client documents its own MCP setup: + +| Client | MCP setup guide | +| --- | --- | +| Claude Code | [Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp) | +| Codex | [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) | +| Cursor | [Model Context Protocol (MCP)](https://cursor.com/docs/mcp) | +| GitHub Copilot | [Extend Copilot Chat with MCP](https://docs.github.com/en/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp) | +| OpenCode | [MCP servers](https://opencode.ai/docs/mcp-servers/) | + 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: @@ -126,22 +138,29 @@ 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**: 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: +- **API / your team's internal service**: When a service has neither a CLI nor an MCP server, run `/aidd-context:04-skill-generate` starting from its API. Keep the token in an environment variable, never in the prompt, and read the account: ```bash curl --fail --silent --show-error \ - -H "Authorization: Bearer $GITHUB_TOKEN" \ - https://api.github.com/user + -H "Authorization: Bearer $INTERNAL_API_TOKEN" \ + https://api.internal.example.com/v1/me + ``` + +- **SDK / Stripe in application code**: Call the service through its [official client](https://github.com/stripe/stripe-node), the key read from the environment: + + ```js + import Stripe from "stripe"; + + const stripe = new Stripe(process.env.STRIPE_SECRET_KEY); + const customers = await stripe.customers.list({ limit: 1 }); ``` 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 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): +After recording the services and their targets in project memory, run the access check. It probes each access read-only and reports what to fix: -- Run this prompt after recording the services and targets in project memory: - - ```text - Verify this project's connections against aidd_docs/memory/. - ``` +```text +/aidd-context:13-access-check +``` From 489e2e8f15a818025f8f7e386bd95a41e744847c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 20 Oct 2026 03:44:46 +0000 Subject: [PATCH 22/32] docs(aidd-context): record how the access check answers the review --- .../2026_10_14_connect-services/challenge.md | 23 ++++++++++----- .../2026_10_14_connect-services/phase-4.md | 2 +- .../2026_10_14_connect-services/plan.md | 2 +- .../2026_10_14_connect-services/review.md | 29 ++++++++++++++----- .../13-access-check/actions/01-check.md | 5 ++-- 5 files changed, 41 insertions(+), 20 deletions(-) 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 index 188891b1a..bedb5b91c 100644 --- 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 @@ -1,14 +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. +**Scope:** Service access verification extracted from `02-project-memory` into `aidd-context:13-access-check`, the recipe reworked after the 2026-10-15 review, and onboarding ending its foundations with the check. +**Evidence limits:** The skill was run by hand against this repository's memory on 2026-10-20; MCP, `http` and `web` probes were not exercised, this bank has `cli` edges only. Client guide URLs checked 2026-10-20. ## 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. +- **Scope:** `02-project-memory/` is identical to `origin/next`; access checking is a separate, read-only skill whose service list comes from `ecosystem.md`, never from the recipe. +- **Placement:** No file of `13-access-check/` links outside it; the recipe names the skill by slash command only. +- **Live run:** One row per `Agent` edge of this bank, `Human` and `App` edges skipped: + + | Tool | Mode | Account / target | Status | Evidence / next step | + | --- | --- | --- | --- | --- | + | GitHub | `gh` | `alexsoyes` / `ai-driven-dev/framework` | ⚠️ | `gh repo view` read the repo; record the expected account in `vcs.md` | + | Roadmap board | `gh` | `alexsoyes` / org project 8 | ⚠️ | `gh project view 8` read 119 items; record the expected account in `backlog.md` | + | AI coding tool | `aidd` | β€” | πŸ”Œ | `aidd` not on `PATH`; install `@ai-driven-dev/cli` | + +- **Empty bank:** A directory without `aidd_docs/memory/` stops at Require with `/aidd-context:02-project-memory`, no file written. +- **Recipe:** CLI, MCP, API and SDK each have one example; none targets a service whose CLI the recipe lists; tokens come from the environment; five client MCP guides answer 200. ## Blockers @@ -18,4 +25,4 @@ None. | 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 | +| Banks label `Agent` edges with a command (`gh`) as often as a mode (`cli`) | this repository's `ecosystem.md` | `ecosystem-signals.md` could state which one an edge carries; the check reads both meanwhile | diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md index 8b1143f37..6bce9fbba 100644 --- a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/phase-4.md @@ -1,5 +1,5 @@ --- -status: pending +status: in-progress --- # Instruction: Record the change and prove it end to end diff --git a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md index 45bcc4bfc..7f167fcd0 100644 --- a/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md +++ b/aidd_docs/tasks/2026_10/2026_10_14_connect-services/plan.md @@ -1,6 +1,6 @@ --- objective: "Service access verification lives in its own read-only aidd-context skill driven by project memory, 02-project-memory is back to memory only, and connect-services.md addresses the PR #1026 review." -status: in-progress +status: implemented --- # Plan: Move service access verification into `aidd-context:13-access-check` 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 index 34dbdc77b..4e2298c6a 100644 --- 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 @@ -17,13 +17,10 @@ - [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 +### Phase 2: Access check skill (reworked 2026-10-20) -- [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`. +- [x] Verification leaves `02-project-memory`, back to `origin/next`; it lives in `13-access-check`, read-only, one row per `Agent` edge of `ecosystem.md`: `13-access-check/actions/01-check.md`, `13-access-check/assets/access-report.md`. +- [x] No memory proposes `/aidd-context:02-project-memory`, never runs it; onboarding offers the check as the last foundation of a setup session: `00-onboard/references/state/zones.md`. ### Phase 3: Validator support @@ -33,6 +30,22 @@ None. +## Review of 2026-10-15 + +| # | Finding | Resolution | +| --- | --- | --- | +| 1 | `02-project-memory` does too much | verification moved to `13-access-check` | +| 2 | the action resolves the recipe by relative path | the skill reads memory only, no recipe | +| 3 | four options announced, two shown | recipe step 2 shows CLI, MCP, API and SDK | +| 4 | examples cover Claude Code only | one example plus a table of five clients' MCP guides; the former recipe named no other client either | +| 5 | the GitHub API example contradicts CLI-first | replaced by an internal API with no CLI or MCP | +| 6 | why generate a skill for an API | the recipe says to run `/aidd-context:04-skill-generate` from the API when no CLI or MCP exists | +| 7 | no link to project memory | the intro names `ecosystem.md` and `/aidd-context:02-project-memory` | +| 8 | nothing on errors | ❌ with one corrective action, next row still probed; missing memory stops with a proposal | +| 9 | the description loses its meaning | `02-project-memory` description restored | +| 10 | `check` beside `verify` is confusing | `verify` left the skill | +| 11 | "report of what changed" does not fit verify | rule untouched, verify left the skill | + ## Verification | Metric | Value | @@ -45,5 +58,5 @@ None. | 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 | +| Non-blocking clarity | resolved 2026-10-20: the access check reads memory only, no recipe resolution remains | +| Non-blocking router consistency | resolved 2026-10-20: verify left `02-project-memory`, its report rule fits every entry again | diff --git a/plugins/aidd-context/skills/13-access-check/actions/01-check.md b/plugins/aidd-context/skills/13-access-check/actions/01-check.md index b42b47143..8b88675e0 100644 --- a/plugins/aidd-context/skills/13-access-check/actions/01-check.md +++ b/plugins/aidd-context/skills/13-access-check/actions/01-check.md @@ -5,7 +5,7 @@ Probe each access the project memory records for the assistant, then fill the re ## Input - `aidd_docs/memory/ecosystem.md`: the services and how each actor reaches them. -- `aidd_docs/memory/vcs.md` and `aidd_docs/memory/backlog.md`, when present: the expected accounts and targets. +- The memory file each tool's node names, such as `vcs.md` or `backlog.md`: the expected account and target. - Optionally, one tool name, to check that tool only. ## Output @@ -18,7 +18,8 @@ A printed report from [access-report.md](../assets/access-report.md), or one sto - `aidd_docs/memory/` holds no `.md`: propose `/aidd-context:02-project-memory` to set up the memory. - No `ecosystem.md`: propose `/aidd-context:02-project-memory refresh` to add it. - No `Agent` edge in `ecosystem.md`: report that nothing is for the assistant to check. -2. **Map.** One row per `Agent -- --> ` edge. +2. **Map.** One row per `Agent --