From 9421023fee6cf694c81159f5194817ccdf902bee Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Wed, 27 May 2026 10:11:58 -0500 Subject: [PATCH 1/2] Move repository skills to .agents Consolidate repository-owned skill files under .agents/skills and update repo guidance references to the standard location. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- {.claude => .agents}/skills/aspire/SKILL.md | 0 .../skills/doc-tester/SKILL.md | 0 .../skills/doc-writer/SKILL.md | 0 .../references/terminal-recordings.md | 2 +- {.github => .agents}/skills/hex1b/SKILL.md | 2 +- .../skills/playwright-cli/SKILL.md | 0 .../skills/update-integrations/SKILL.md | 0 .../skills/update-samples/SKILL.md | 0 .github/agents/release-verifier.agent.md | 8 +- .github/skills/aspire/SKILL.md | 93 ------------------- .opencode/skill/aspire/SKILL.md | 93 ------------------- 11 files changed, 6 insertions(+), 192 deletions(-) rename {.claude => .agents}/skills/aspire/SKILL.md (100%) rename {.github => .agents}/skills/doc-tester/SKILL.md (100%) rename {.github => .agents}/skills/doc-writer/SKILL.md (100%) rename {.github => .agents}/skills/doc-writer/references/terminal-recordings.md (99%) rename {.github => .agents}/skills/hex1b/SKILL.md (99%) rename {.github => .agents}/skills/playwright-cli/SKILL.md (100%) rename {.github => .agents}/skills/update-integrations/SKILL.md (100%) rename {.github => .agents}/skills/update-samples/SKILL.md (100%) delete mode 100644 .github/skills/aspire/SKILL.md delete mode 100644 .opencode/skill/aspire/SKILL.md diff --git a/.claude/skills/aspire/SKILL.md b/.agents/skills/aspire/SKILL.md similarity index 100% rename from .claude/skills/aspire/SKILL.md rename to .agents/skills/aspire/SKILL.md diff --git a/.github/skills/doc-tester/SKILL.md b/.agents/skills/doc-tester/SKILL.md similarity index 100% rename from .github/skills/doc-tester/SKILL.md rename to .agents/skills/doc-tester/SKILL.md diff --git a/.github/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md similarity index 100% rename from .github/skills/doc-writer/SKILL.md rename to .agents/skills/doc-writer/SKILL.md diff --git a/.github/skills/doc-writer/references/terminal-recordings.md b/.agents/skills/doc-writer/references/terminal-recordings.md similarity index 99% rename from .github/skills/doc-writer/references/terminal-recordings.md rename to .agents/skills/doc-writer/references/terminal-recordings.md index 56ad4151b..0d6889609 100644 --- a/.github/skills/doc-writer/references/terminal-recordings.md +++ b/.agents/skills/doc-writer/references/terminal-recordings.md @@ -306,7 +306,7 @@ dotnet hex1b terminal attach Generate this skill file for a repository so AI agents know how to use the CLI. ```bash -# Write skill file to .github/skills/hex1b/SKILL.md +# Write skill file to .agents/skills/hex1b/SKILL.md dotnet hex1b agent init # Specify a different repo root diff --git a/.github/skills/hex1b/SKILL.md b/.agents/skills/hex1b/SKILL.md similarity index 99% rename from .github/skills/hex1b/SKILL.md rename to .agents/skills/hex1b/SKILL.md index fcdf3f9e6..07e06b909 100644 --- a/.github/skills/hex1b/SKILL.md +++ b/.agents/skills/hex1b/SKILL.md @@ -274,7 +274,7 @@ dotnet hex1b terminal attach Generate this skill file for a repository so AI agents know how to use the CLI. ```bash -# Write skill file to .github/skills/hex1b/SKILL.md +# Write skill file to .agents/skills/hex1b/SKILL.md dotnet hex1b agent init # Specify a different repo root diff --git a/.github/skills/playwright-cli/SKILL.md b/.agents/skills/playwright-cli/SKILL.md similarity index 100% rename from .github/skills/playwright-cli/SKILL.md rename to .agents/skills/playwright-cli/SKILL.md diff --git a/.github/skills/update-integrations/SKILL.md b/.agents/skills/update-integrations/SKILL.md similarity index 100% rename from .github/skills/update-integrations/SKILL.md rename to .agents/skills/update-integrations/SKILL.md diff --git a/.github/skills/update-samples/SKILL.md b/.agents/skills/update-samples/SKILL.md similarity index 100% rename from .github/skills/update-samples/SKILL.md rename to .agents/skills/update-samples/SKILL.md diff --git a/.github/agents/release-verifier.agent.md b/.github/agents/release-verifier.agent.md index ae2e6813b..6fbab2d2b 100644 --- a/.github/agents/release-verifier.agent.md +++ b/.github/agents/release-verifier.agent.md @@ -299,7 +299,7 @@ This agent depends on the following skills. Read the full skill instructions bef | Skill | File | When used | |-------|------|-----------| -| doc-tester | `.github/skills/doc-tester/SKILL.md` | Phase 3 (content validation), Phase 6 (smoke test) | -| hex1b | `.github/skills/hex1b/SKILL.md` | Phase 2 (preview server management), terminal capture | -| playwright-cli | `.github/skills/playwright-cli/SKILL.md` | Phase 3d, Phase 6 (browser-based verification) | -| update-integrations | `.github/skills/update-integrations/SKILL.md` | Phase 5 (integration docs sync) | +| doc-tester | `.agents/skills/doc-tester/SKILL.md` | Phase 3 (content validation), Phase 6 (smoke test) | +| hex1b | `.agents/skills/hex1b/SKILL.md` | Phase 2 (preview server management), terminal capture | +| playwright-cli | `.agents/skills/playwright-cli/SKILL.md` | Phase 3d, Phase 6 (browser-based verification) | +| update-integrations | `.agents/skills/update-integrations/SKILL.md` | Phase 5 (integration docs sync) | diff --git a/.github/skills/aspire/SKILL.md b/.github/skills/aspire/SKILL.md deleted file mode 100644 index bbdc8be52..000000000 --- a/.github/skills/aspire/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: aspire -description: "Orchestrates Aspire distributed applications using the Aspire CLI for running, debugging, and managing distributed apps. USE FOR: aspire start, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire CLI commands (aspire start, aspire describe, aspire otel logs, aspire docs search, aspire add), bash. FOR SINGLE OPERATIONS: Use Aspire CLI commands directly for quick resource status or doc lookups." ---- - -# Aspire Skill - -This repository uses Aspire to orchestrate its distributed application. Resources are defined in the AppHost project (`apphost.cs` or `apphost.ts`). - -## CLI command reference - -| Task | Command | -|---|---| -| Start the app | `aspire start` | -| Start isolated (worktrees) | `aspire start --isolated` | -| Restart the app | `aspire start` (stops previous automatically) | -| Wait for resource healthy | `aspire wait ` | -| Stop the app | `aspire stop` | -| List resources | `aspire describe` or `aspire resources` | -| Run resource command | `aspire resource ` | -| Start/stop/restart resource | `aspire resource start|stop|restart` | -| View console logs | `aspire logs [resource]` | -| View structured logs | `aspire otel logs [resource]` | -| View traces | `aspire otel traces [resource]` | -| Logs for a trace | `aspire otel logs --trace-id ` | -| Add an integration | `aspire add` | -| List running AppHosts | `aspire ps` | -| Update AppHost packages | `aspire update` | -| Search docs | `aspire docs search ` | -| Get doc page | `aspire docs get ` | -| List doc pages | `aspire docs list` | -| Environment diagnostics | `aspire doctor` | -| List resource MCP tools | `aspire mcp tools` | -| Call resource MCP tool | `aspire mcp call --input ` | - -Most commands support `--format Json` for machine-readable output. Use `--apphost ` to target a specific AppHost. - -## Key workflows - -### Running in agent environments - -Use `aspire start` to run the AppHost in the background. When working in a git worktree, use `--isolated` to avoid port conflicts and to prevent sharing user secrets or other local state with other running instances: - -```bash -aspire start --isolated -``` - -Use `aspire wait ` to block until a resource is healthy before interacting with it: - -```bash -aspire start --isolated -aspire wait myapi -``` - -Relaunching is safe — `aspire start` automatically stops any previous instance. Re-run `aspire start` whenever changes are made to the AppHost project. - -### Debugging issues - -Before making code changes, inspect the app state: - -1. `aspire describe` — check resource status -2. `aspire otel logs ` — view structured logs -3. `aspire logs ` — view console output -4. `aspire otel traces ` — view distributed traces - -### Adding integrations - -Use `aspire docs search` to find integration documentation, then `aspire docs get` to read the full guide. Use `aspire add` to add the integration package to the AppHost. - -After adding an integration, restart the app with `aspire start` for the new resource to take effect. - -### Using resource MCP tools - -Some resources expose MCP tools (e.g. `WithPostgresMcp()` adds SQL query tools). Discover and call them via CLI: - -```bash -aspire mcp tools # list available tools -aspire mcp tools --format Json # includes input schemas -aspire mcp call --input '{"key":"value"}' # invoke a tool -``` - -## Important rules - -- **Always start the app first** (`aspire start`) before making changes to verify the starting state. -- **To restart, just run `aspire start` again** — it automatically stops the previous instance. NEVER use `aspire stop` then `aspire run`. NEVER use `aspire run` at all. -- Use `--isolated` when working in a worktree. -- **Avoid persistent containers** early in development to prevent state management issues. -- **Never install the Aspire workload** — it is obsolete. -- Prefer `aspire.dev` and `learn.microsoft.com/microsoft/aspire` for official documentation. - -## Playwright CLI - -If configured, use Playwright CLI for functional testing of resources. Get endpoints via `aspire describe`. Run `playwright-cli --help` for available commands. \ No newline at end of file diff --git a/.opencode/skill/aspire/SKILL.md b/.opencode/skill/aspire/SKILL.md deleted file mode 100644 index bbdc8be52..000000000 --- a/.opencode/skill/aspire/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: aspire -description: "Orchestrates Aspire distributed applications using the Aspire CLI for running, debugging, and managing distributed apps. USE FOR: aspire start, aspire stop, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire logs, add aspire resource, aspire dashboard, update aspire apphost. DO NOT USE FOR: non-Aspire .NET apps (use dotnet CLI), container-only deployments (use docker/podman), Azure deployment after local testing (use azure-deploy skill). INVOKES: Aspire CLI commands (aspire start, aspire describe, aspire otel logs, aspire docs search, aspire add), bash. FOR SINGLE OPERATIONS: Use Aspire CLI commands directly for quick resource status or doc lookups." ---- - -# Aspire Skill - -This repository uses Aspire to orchestrate its distributed application. Resources are defined in the AppHost project (`apphost.cs` or `apphost.ts`). - -## CLI command reference - -| Task | Command | -|---|---| -| Start the app | `aspire start` | -| Start isolated (worktrees) | `aspire start --isolated` | -| Restart the app | `aspire start` (stops previous automatically) | -| Wait for resource healthy | `aspire wait ` | -| Stop the app | `aspire stop` | -| List resources | `aspire describe` or `aspire resources` | -| Run resource command | `aspire resource ` | -| Start/stop/restart resource | `aspire resource start|stop|restart` | -| View console logs | `aspire logs [resource]` | -| View structured logs | `aspire otel logs [resource]` | -| View traces | `aspire otel traces [resource]` | -| Logs for a trace | `aspire otel logs --trace-id ` | -| Add an integration | `aspire add` | -| List running AppHosts | `aspire ps` | -| Update AppHost packages | `aspire update` | -| Search docs | `aspire docs search ` | -| Get doc page | `aspire docs get ` | -| List doc pages | `aspire docs list` | -| Environment diagnostics | `aspire doctor` | -| List resource MCP tools | `aspire mcp tools` | -| Call resource MCP tool | `aspire mcp call --input ` | - -Most commands support `--format Json` for machine-readable output. Use `--apphost ` to target a specific AppHost. - -## Key workflows - -### Running in agent environments - -Use `aspire start` to run the AppHost in the background. When working in a git worktree, use `--isolated` to avoid port conflicts and to prevent sharing user secrets or other local state with other running instances: - -```bash -aspire start --isolated -``` - -Use `aspire wait ` to block until a resource is healthy before interacting with it: - -```bash -aspire start --isolated -aspire wait myapi -``` - -Relaunching is safe — `aspire start` automatically stops any previous instance. Re-run `aspire start` whenever changes are made to the AppHost project. - -### Debugging issues - -Before making code changes, inspect the app state: - -1. `aspire describe` — check resource status -2. `aspire otel logs ` — view structured logs -3. `aspire logs ` — view console output -4. `aspire otel traces ` — view distributed traces - -### Adding integrations - -Use `aspire docs search` to find integration documentation, then `aspire docs get` to read the full guide. Use `aspire add` to add the integration package to the AppHost. - -After adding an integration, restart the app with `aspire start` for the new resource to take effect. - -### Using resource MCP tools - -Some resources expose MCP tools (e.g. `WithPostgresMcp()` adds SQL query tools). Discover and call them via CLI: - -```bash -aspire mcp tools # list available tools -aspire mcp tools --format Json # includes input schemas -aspire mcp call --input '{"key":"value"}' # invoke a tool -``` - -## Important rules - -- **Always start the app first** (`aspire start`) before making changes to verify the starting state. -- **To restart, just run `aspire start` again** — it automatically stops the previous instance. NEVER use `aspire stop` then `aspire run`. NEVER use `aspire run` at all. -- Use `--isolated` when working in a worktree. -- **Avoid persistent containers** early in development to prevent state management issues. -- **Never install the Aspire workload** — it is obsolete. -- Prefer `aspire.dev` and `learn.microsoft.com/microsoft/aspire` for official documentation. - -## Playwright CLI - -If configured, use Playwright CLI for functional testing of resources. Get endpoints via `aspire describe`. Run `playwright-cli --help` for available commands. \ No newline at end of file From e8135e43d78fd608d7fe5761a101c8895969d06d Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Fri, 29 May 2026 10:55:51 -0500 Subject: [PATCH 2/2] Prefer playwright-cli in doc skills Update doc-writer and doc-tester guidance to direct browser-based validation through playwright-cli instead of MCP-backed browser tooling. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .agents/skills/doc-tester/SKILL.md | 62 ++++++++++++++---------------- .agents/skills/doc-writer/SKILL.md | 10 +++-- 2 files changed, 35 insertions(+), 37 deletions(-) diff --git a/.agents/skills/doc-tester/SKILL.md b/.agents/skills/doc-tester/SKILL.md index bfd712092..3879d42ef 100644 --- a/.agents/skills/doc-tester/SKILL.md +++ b/.agents/skills/doc-tester/SKILL.md @@ -13,7 +13,7 @@ This skill provides guidelines for AI agents to systematically validate the aspi ### Core Principles -1. **Use Playwright exclusively** to browse and interact with the documentation site +1. **Use `playwright-cli` exclusively** to browse and interact with the documentation site 2. **Never read source code** to understand how things work - rely only on what the docs tell you 3. **Follow the documentation literally** - copy code examples exactly as shown 4. **Evaluate teaching effectiveness** - can you learn from this documentation? @@ -28,7 +28,7 @@ This skill provides guidelines for AI agents to systematically validate the aspi - Silently fill gaps with your built-in knowledge - flag them instead ✅ **DO:** -- Use Playwright MCP tools to navigate the documentation site +- Use `playwright-cli` commands to navigate the documentation site - Read documentation content as displayed in the browser - Copy code examples and run them in test projects - Evaluate if explanations make sense without prior knowledge @@ -185,7 +185,7 @@ iex "& { $(irm https://aspire.dev/install.ps1) } -Quality 'staging'" ### Aspire App Model -The aspire.dev workspace uses Aspire to orchestrate local services. The app model in `apphost.cs` defines the documentation site resources. Use `mcp_aspire_list_resources` to get the current resource states and URLs. +The aspire.dev workspace uses Aspire to orchestrate local services. The app model in `apphost.cs` defines the documentation site resources. Use the Aspire CLI output or dashboard resource list to get the current resource states and URLs. ### Starting the Local Environment @@ -200,15 +200,7 @@ cd /path/to/aspire.dev aspire run ``` -Use the Aspire MCP tools to get the content URL: - -``` -# Call the MCP tool -mcp_aspire_list_resources - -# Look for the frontend resource endpoint_urls -# Example output: http://frontend.dev.localhost:5000 -``` +Use the Aspire CLI output or dashboard resource list to get the content URL. Look for the `frontend` resource endpoint URL, for example `http://frontend.dev.localhost:5000`. **IMPORTANT**: Use the local frontend URL for all testing, not https://aspire.dev @@ -299,27 +291,30 @@ The documentation site includes: ## Testing Workflow -**All testing uses Playwright MCP tools to interact with the documentation site.** +**All browser-based testing uses `playwright-cli` to interact with the documentation site.** ### Phase 0: Environment Preparation 1. **Start Aspire**: Run `aspire run` from the repository root -2. **Get frontend URL**: Use `mcp_aspire_list_resources` to find the `frontend` endpoint +2. **Get frontend URL**: Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint 3. **Note the URL**: The script outputs the local development URL ### Phase 1: Navigate and Read Documentation (Playwright) -Use Playwright MCP tools to browse the documentation: +Use `playwright-cli` to browse the documentation: + +```bash +# Open the local docs site +playwright-cli open http://frontend.dev.localhost:5000 -``` # Take an accessibility snapshot to read page content -mcp_playwright_browser_snapshot +playwright-cli snapshot -# Navigate to a page -mcp_playwright_browser_click with element="Getting Started link" +# Navigate to a page by clicking a ref from the snapshot +playwright-cli click e42 # Read page content -mcp_playwright_browser_snapshot +playwright-cli snapshot ``` For each documentation page: @@ -652,28 +647,29 @@ Keep the workspace directory but remove contents to avoid cluttering the reposit 4. Document any place where you got stuck 5. Verify final result matches what's promised -## Using MCP Tools +## Using CLI Tools -### Aspire MCP Tools +### Aspire CLI Use for checking resource status: -``` -mcp_aspire_list_resources # Get all resources and URLs -mcp_aspire_list_console_logs # Check resource logs -mcp_aspire_list_structured_logs # Check structured logs +```bash +aspire run # Start the app and print resource URLs +aspire ps --include-hidden # List running resources and URLs when using aspire start +aspire describe # Inspect AppHost resources and endpoints ``` -### Playwright MCP Tools +### `playwright-cli` Use for navigating and reading documentation: -``` -mcp_playwright_browser_navigate # Go to a URL -mcp_playwright_browser_snapshot # Read page content -mcp_playwright_browser_click # Click elements -mcp_playwright_browser_type # Type text -mcp_playwright_browser_screenshot # Capture screenshot +```bash +playwright-cli open # Open a browser at a URL +playwright-cli goto # Navigate to a URL +playwright-cli snapshot # Read page content +playwright-cli click # Click an element from the snapshot +playwright-cli type "text" # Type text into the active element +playwright-cli screenshot # Capture a screenshot ``` ### Hex1b CLI Tools diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 0b782d768..41318c2ac 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -832,6 +832,7 @@ Use the smallest set of checks that proves the change is correct: - For custom component usage changes, run the component render tests that cover the affected behavior. - For component prop surface changes, update and run the prop-contract coverage so editor completions and consumer typings stay intact. - For interactive behavior changes, run targeted Playwright coverage for the scenario you changed rather than relying on unrelated broad suites. +- For browser-based local verification, use `playwright-cli` (`playwright-cli open `, `playwright-cli snapshot`, `playwright-cli click `) instead of Playwright MCP tools. - For accessibility-sensitive changes, validate both the rendered page and any focused accessibility tests that exercise the affected interaction. ### Custom Component and Test Expectations @@ -929,13 +930,14 @@ aspire run When testing code examples that add integration packages, use `aspire add ` rather than `dotnet add package`. The Aspire CLI automatically adds packages to the correct project. -Use the Aspire MCP tools to check the status of resources: +Use the Aspire CLI output or dashboard resource list to find the `frontend` endpoint, then open it with `playwright-cli`: -``` -mcp_aspire_list_resources +```bash +playwright-cli open +playwright-cli snapshot ``` -Navigate to the `frontend` resource endpoint to view the documentation site. +Use snapshot refs with `playwright-cli click ` for page interactions. ## Cross-Referencing