opencastle 0.32.4 → 0.32.6

package/src/orchestrator/plugins/nx/SKILL.md

@@ -96,98 +96,46 @@ The NX MCP server provides tools for understanding and working with the workspac
 
 ## Code Generation Workflow
 
-Use this workflow whenever scaffolding new code (libraries, applications, features) or running automated code transformations. **Always prefer generators over manual file creation** when a generator exists for the task.
+Always prefer generators over manual file creation when a generator exists.
 
 ### Phase 1: Discover
 
-1. **List available generators** using `nx_generators` MCP tool
-   - This includes plugin generators (e.g., `@nx/react:library`) and local workspace generators
-2. **Match generator to request** — identify which generator(s) could fulfill the need
-3. **Prefer local generators** — when both local and plugin generators could work, **always prefer local** (they're customized for this repo's patterns)
-4. **If no generator fits** — check `nx_available_plugins` for installable plugins. Only fall back to manual creation after exhausting all generator options
+1. List available generators using `nx_generators` MCP tool (plugin + local workspace generators)
+2. Prefer local generators over plugin generators — they're customized for this repo
+3. If no generator fits, check `nx_available_plugins`; only fall back to manual creation after exhausting all generator options
 
 ### Phase 2: Understand
 
-Before running any generator, complete these steps:
-
-1. **Fetch generator schema** using `nx_generator_schema` MCP tool
-   - Identify required vs optional options
-   - Note default values that may need overriding
-   - Pay attention to options that affect file structure or naming
-
-2. **Read generator source code** (for unfamiliar generators)
-   - Find source: `node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"`
-   - If that fails: read from `node_modules/<plugin>/generators.json`
-   - Local generators: check `tools/generators/` or local plugin directories
-   - Understanding the source reveals side effects (config updates, dep installs) and files created/modified
-
-3. **Reevaluate generator choice** — after understanding what the generator does, confirm it's the right one. If not, go back to Phase 1 and select a different generator.
-
-4. **Examine repo context** — study existing similar artifacts in the codebase:
-   - Look at how similar projects are structured (naming, test runner, build tool, linter)
-   - Match conventions when configuring the generator
-   - Note directory structures, file patterns, and config styles
-
-5. **Validate required options** — map the user's request to generator options:
-   - Infer values from context where possible
-   - Ask for critical missing information if it cannot be inferred
+1. Fetch generator schema using `nx_generator_schema` — note required options, defaults, and file structure impacts
+2. Read generator source to understand side effects (config updates, dep installs, files created/modified)
+3. Examine existing similar artifacts for naming, structure, test runner, and config conventions; map user's request to generator options
 
 ### Phase 3: Execute
 
-1. **Consider dry-run first** (recommended for complex/unfamiliar generators):
-   ```bash
-   yarn nx generate <generator-name> <options> --dry-run --no-interactive
-   ```
-   - Shows files that would be created/deleted/modified (but not content)
-   - Some generators don't support dry-run (e.g., if they install packages) — skip and run for real
-   - For simple, well-understood generators, you may skip dry-run
+```bash
+yarn nx generate <generator-name> <options> --dry-run --no-interactive  # optional preview
+yarn nx generate <generator-name> <options> --no-interactive
+```
 
-2. **Run the generator**:
-   ```bash
-   yarn nx generate <generator-name> <options> --no-interactive
-   ```
-   **CRITICAL**: Always include `--no-interactive` to prevent prompts that hang execution.
+**CRITICAL**: Always include `--no-interactive` to prevent prompts that hang execution.
 
-   **CRITICAL**: Generators may behave differently based on the current working directory (e.g., library generators use cwd to determine placement). Verify cwd before running.
+**CRITICAL**: Verify cwd before running — generators may use it to determine file placement.
 
-3. **Handle failures** — if the generator fails:
-   - Read the error message carefully
-   - Common causes: missing required options, invalid values, conflicting files, missing dependencies
-   - Adjust options and retry
-   - Use the **self-improvement** skill to add a lesson if the fix was non-obvious
+On failure: read the error, adjust options, and retry. Use the **self-improvement** skill for non-obvious fixes.
 
 ### Phase 4: Post-Generation
 
-1. **Modify generated code** if needed — generators provide a starting point:
-   - Adjust functionality to match specific requirements
-   - Update imports, exports, configurations
-   - Integrate with existing code patterns
-
-2. **Format code**:
-   ```bash
-   yarn nx format --fix
-   ```
-
-3. **Run verification** on generated/affected projects:
-   ```bash
-   yarn nx run <new-project>:lint --fix
-   yarn nx run <new-project>:test
-   yarn nx run <new-project>:build
-   ```
-
-4. **Handle verification failures**:
-   - **Small scope** (few lint errors, minor type issues) — fix directly, re-verify
-   - **Large scope** (many errors, complex problems) — fix obvious issues first, escalate remaining with description of what was generated, what's failing, and what was attempted
+1. Modify generated code to match requirements (imports, exports, config, integrations)
+2. Format: `yarn nx format --fix`
+3. Verify lint, test, and build on generated/affected projects; fix small-scope issues directly, escalate large-scope failures
 
 ## Running Tasks Workflow
 
-When helping with build, test, lint, or serve tasks:
-
 1. Use `nx_current_running_tasks_details` to check for active/completed/failed tasks
-2. For a specific task, use `nx_current_running_task_output` to get its terminal output
+2. Use `nx_current_running_task_output` to get terminal output for a specific task
 3. Diagnose issues from the output and apply fixes
-4. To rerun a task, always use `yarn nx run <taskId>` to preserve the NX context
-5. **Continuous tasks** (like `serve`) are already running — don't offer to rerun, just check output
+4. To rerun, use `yarn nx run <taskId>` to preserve NX context
+5. **Continuous tasks** (like `serve`) are already running — don't rerun, just check output
 
 ## Project Names
 

package/src/orchestrator/plugins/playwright/SKILL.md

@@ -103,25 +103,12 @@ export class LoginPage {
 }
 ```
 
-### Custom Fixtures
+## API Mocking
 
 ```typescript
-// tests/fixtures/auth.fixture.ts
-import { test as base } from '@playwright/test';
-
-type AuthFixtures = {
-  authenticatedPage: Page;
-};
-
-export const test = base.extend<AuthFixtures>({
-  authenticatedPage: async ({ page }, use) => {
-    await page.goto('/login');
-    await page.getByTestId('email-input').fill('test@example.com');
-    await page.getByTestId('password-input').fill('password');
-    await page.getByTestId('login-button').click();
-    await page.waitForURL('**/dashboard');
-    await use(page);
-  },
+// Mock API responses for deterministic tests
+await page.route('/api/login', (route) => {
+  route.fulfill({ status: 200, body: JSON.stringify({ token: 'test' }) });
 });
 ```
 
@@ -189,3 +176,4 @@ The Playwright MCP server enables AI agents to interact with browsers directly:
 - Run tests in parallel (`fullyParallel: true`) for speed
 - Use `trace: 'on-first-retry'` to debug flaky tests
 - Use `codegen` to bootstrap tests, then refactor into page objects
+- Use `page.route()` to mock API responses — create isolated, deterministic tests without backend dependencies

package/src/orchestrator/plugins/slack/SKILL.md

@@ -15,95 +15,55 @@ Agent communication patterns via the Slack MCP server. Enables agents to post pr
 |-------|-------|
 | **Package** | [`@kazuph/mcp-slack`](https://www.npmjs.com/package/@kazuph/mcp-slack) |
 | **Type** | stdio (spawned via `npx -y @kazuph/mcp-slack`) |
-| **Auth** | Bot token (`xoxb-…`) via `SLACK_MCP_XOXB_TOKEN` env var (loaded from `.env` or `envFile`) |
-| **Extra env** | `SLACK_MCP_ADD_MESSAGE_TOOL=true` — enables the `conversations_add_message` tool |
-| **Supported clients** | VS Code, Claude Code, Cursor, any MCP-compatible client with stdio support |
+| **Auth** | Bot token (`xoxb-…`) via `SLACK_MCP_XOXB_TOKEN` env var |
+| **Extra env** | `SLACK_MCP_ADD_MESSAGE_TOOL=true` — enables `conversations_add_message` |
 
 ### Authentication
 
-The `@kazuph/mcp-slack` server supports multiple token types (only one is needed):
+Use a **bot token** (`SLACK_MCP_XOXB_TOKEN`). For message search, a user token (`xoxp-…`) via `SLACK_MCP_XOXP_TOKEN` is required instead.
 
-| Env Variable | Token Type | Notes |
-|-------------|------------|-------|
-| `SLACK_MCP_XOXB_TOKEN` | Bot token (`xoxb-…`) | Limited to invited channels only, no search |
-| `SLACK_MCP_XOXP_TOKEN` | User OAuth token (`xoxp-…`) | Full access, requires OAuth app setup |
-| `SLACK_MCP_XOXC_TOKEN` + `SLACK_MCP_XOXD_TOKEN` | Browser tokens | "Stealth mode" — no app install needed |
-
-This project uses a **bot token** (`SLACK_MCP_XOXB_TOKEN`). Add these under **Bot Token Scopes** in the Slack app configuration:
+**Bot Token Scopes:**
 
 | Scope | Purpose |
 |-------|---------|
 | `chat:write` | Post messages and replies |
-| `channels:read` | List public channels and their metadata |
-| `channels:history` | Read messages in public channels |
-| `channels:manage` | Create/rename channels, set topics (optional) |
-| `groups:read` | List private channels |
-| `groups:history` | Read messages in private channels |
-| `im:read` | List direct message conversations |
-| `im:history` | Read direct messages |
-| `mpim:read` | List group DM conversations |
-| `mpim:history` | Read group DMs |
-| `users:read` | Look up user profiles |
-| `users:read.email` | Look up user emails |
-
-> **Note:** `channels:manage` is optional — only needed if agents should create channels or rename them. Without it, `conversations_create` and `conversations_rename` will return `missing_scope`.
-> 
-> **Note:** Bot tokens cannot search messages. If search is needed, use a user token (`xoxp-…`) instead.
-
-Admin approval is required. Work with the workspace admin to install the app.
+| `channels:read`, `channels:history` | List and read public channels |
+| `groups:read`, `groups:history` | List and read private channels |
+| `im:read`, `im:history`, `mpim:read`, `mpim:history` | DMs and group DMs |
+| `users:read`, `users:read.email` | Look up user profiles and emails |
+| `channels:manage` | Create/rename channels (optional) |
 
 ## Available MCP Tools
 
-The Slack MCP server exposes the following tools (prefixed with `mcp_slack_` in VS Code / Copilot):
-
 ### Channel Management
 
-| Tool | Description | Key Parameters |
-|------|-------------|----------------|
-| `channels_list` | List workspace channels | `channel_types` (public/private), `limit`, `cursor` |
-| `conversations_create` | Create a new channel | `name` (required). Needs `channels:manage` scope |
-| `conversations_rename` | Rename a channel | `channel_id`, `name`. Needs `channels:manage` scope |
-| `conversations_set_topic` | Set a channel's topic | `channel_id`, `topic` |
-| `conversations_invite` | Invite user(s) to a channel | `channel_id`, `users` (comma-separated user IDs) |
+`channels_list`, `conversations_create`, `conversations_rename`, `conversations_set_topic`, `conversations_invite`
 
 ### Messaging
 
 | Tool | Description | Key Parameters |
 |------|-------------|----------------|
-| `conversations_add_message` | Post a message to a channel or thread | `channel_id` (ID or name), `payload` (message text), `content_type` (`text/markdown` or `text/plain`, default: `text/markdown`), `thread_ts` (optional, for threading) |
-| `conversations_history` | Read recent messages from a channel | `channel_id`, `limit` (time range like `1d`/`7d`/`30d` or message count like `50`), `cursor` |
-| `conversations_replies` | Get replies in a thread | `channel_id`, `thread_ts`, `limit`, `cursor` |
-| `conversations_search_messages` | Search messages across channels | `search_query`, `filter_in_channel`, `filter_users_from`, `filter_date_before`/`after`/`on`/`during`, `limit` (1-100) |
+| `conversations_add_message` | Post a message to a channel or thread | `channel_id`, `payload`, `content_type` (`text/markdown`), `thread_ts` |
+| `conversations_history` | Read recent messages from a channel | `channel_id`, `limit` (e.g. `1d`, `50`) |
+| `conversations_replies` | Get replies in a thread | `channel_id`, `thread_ts`, `limit` |
+| `conversations_search_messages` | Search messages across channels | `search_query`, `filter_in_channel`, `filter_date_*` |
 
 ### Users
 
-| Tool | Description | Key Parameters |
-|------|-------------|----------------|
-| `users_resolve` | Look up a user by name or email | Returns user ID for mentions |
-
-### Channel ID Resolution
-
-The `channel_id` parameter in messaging tools accepts:
-- **Channel ID** — e.g., `C0AHAQFJ7C1` (most reliable)
-- **Channel name** — e.g., `new-channel` (without `#` prefix)
-
-When a channel name is ambiguous or not found, use `channels_list` first to get the correct ID.
+`users_resolve` — look up a user by name or email; returns user ID for mentions.
 
-### Key Differences from Documented Slack Web API
+### Key Differences from Slack Web API
 
 - Tool names use `conversations_*` pattern, not `chat.postMessage` etc.
 - Message body is sent via `payload` parameter, not `text`
 - Message posting is **disabled by default** — requires `SLACK_MCP_ADD_MESSAGE_TOOL=true` env var
 - `limit` on history/replies accepts time ranges (`1d`, `7d`, `30d`) or message counts (`50`)
-- No reaction tools — reactions are not available via this MCP server
-- No canvas tools — canvases are not exposed
+- No reaction tools or canvas tools available via this MCP server
 
 ## Agent Notification Patterns
 
 ### Progress Updates
 
-Post structured progress updates to a designated channel:
-
 ```
 Channel: #agent-updates (or project-specific channel)
 Format:
@@ -113,29 +73,11 @@ Format:
   **ETA:** ~5 minutes
 ```
 
-### Completion Notifications
-
-```
-✅ **Task:** TAS-42 — Add price filter component
-**Status:** Complete — PR opened
-**PR:** https://github.com/org/repo/pull/123
-**Summary:** Added PriceRangeFilter with 4 range options, 12 unit tests passing
-```
-
-### Error / Blocking Notifications
-
-```
-🚨 **Task:** TAS-42 — Add price filter component
-**Status:** Blocked — needs human input
-**Issue:** Cannot determine correct price ranges for the market
-**Action needed:** Reply in this thread with the desired price range values
-```
-
 ## Bi-Directional Communication
 
 ### Dual-Channel Approval Pattern
 
-Approval requests are always **dual-channel** — posted to Slack AND asked in the chat window. The first response (from either channel) wins.
+Approval requests are always **dual-channel** — posted to Slack AND asked in the chat window. The first response wins.
 
 ```
 Agent needs approval
@@ -150,8 +92,6 @@ Agent needs approval
        (immediate, no polling needed)
 ```
 
-**Why dual-channel:** The chat path is instant (user's next message is the answer). The Slack path covers the case where the user is away from VS Code (mobile, another machine) and wants to unblock the agent remotely.
-
 ### Approval Flow
 
 1. **Post to Slack** with a structured approval request:
@@ -166,40 +106,13 @@ Agent needs approval
    💬 Or reply with questions
    ```
 
-2. **Ask in chat** — Yield to the user with the same question so they can respond directly in the chat window.
-
-3. **If the user responds in chat** — The agent receives the answer immediately. Post confirmation to the Slack thread:
-   ```
-   ✅ Approved via VS Code chat. Proceeding.
-   ```
-
-4. **If waiting for Slack reply** — While the agent has non-blocked work, poll every 30 seconds:
-   - Use `conversations_replies` with the message's `thread_ts`
-   - Continue with independent subtasks between polls
-   - When a reply arrives, parse it and proceed
-
-5. **If session ends before reply** — Save to checkpoint (see session-checkpoints skill):
-   ```markdown
-   ## Pending Approvals
-   | Provider | Channel | Thread ID | Question | Posted At |
-   |----------|---------|-----------|----------|-----------|
-   | slack | C0AHAQFJ7C1 | 1772393542.345149 | Run migration on production? | 2026-03-01 14:30 |
-   ```
-   The next session's `on-session-start` hook checks for replies.
-
-### Reading User Responses
-
-To check for approvals or instructions:
+2. **Ask in chat** — Yield to the user with the same question so they can respond directly.
 
-1. Use `conversations_replies` with the `thread_ts` of the approval message to read replies
-2. Use `conversations_history` with `oldest`/`latest` time range to find recent directives
-3. Thread replies are the primary mechanism — reactions are not available via MCP
+3. **If the user responds in chat** — Post confirmation to the Slack thread: `✅ Approved via VS Code chat. Proceeding.`
 
-### Resolution Rule
+4. **If waiting for Slack reply** — Poll every 30 seconds using `conversations_replies` with the message's `thread_ts`. Continue independent subtasks between polls.
 
-- **First response wins** — whether from chat or Slack
-- **Cross-post confirmation** — when answered in one channel, post confirmation to the other
-- **Conflicting responses** — if both arrive simultaneously, prefer the chat response (it's more intentional)
+5. **If session ends before reply** — Save to checkpoint with channel, thread ID, question, and timestamp. The next session's `on-session-start` hook checks for replies.
 
 ### Parsing Conventions
 
@@ -211,22 +124,11 @@ To check for approvals or instructions:
 | Thread reply with detailed text | Instructions or questions |
 | `@agent` mention | Direct command or question for the agent |
 
-> **Note:** Reactions (emoji responses) are not available via the Slack MCP server. Use thread replies for all approval workflows.
+> **Note:** Reactions are not available via the Slack MCP server. Use thread replies for all approval workflows.
 
 ## Channel & Thread Conventions
 
-### Channel Configuration
-
-Project-specific channel mappings are defined in `.opencastle/stack/notifications-config.md`. Agents read that file to determine which channel to post to for each event type. Always prefer channel IDs from the config over hardcoded names.
-
-### Default Channel Structure
-
-| Channel | Purpose |
-|---------|---------|
-| `#agent-updates` | General agent activity feed |
-| `#agent-approvals` | Approval requests requiring human action |
-| `#agent-errors` | Error reports and blocked tasks |
-| Project-specific channel | All activity for a specific project |
+Project-specific channel mappings are defined in `.opencastle/stack/notifications-config.md`. Always prefer channel IDs from the config over hardcoded names.
 
 ### Threading Rules
 
@@ -235,79 +137,15 @@ Project-specific channel mappings are defined in `.opencastle/stack/notification
 - **Include task ID** — every message references the tracker issue ID
 - **Pin important threads** — pin approval requests and blocking issues
 
-## Message Formatting
-
-Slack uses a markdown-like syntax with some differences:
-
-| Format | Syntax |
-|--------|--------|
-| Bold | `*bold*` |
-| Italic | `_italic_` |
-| Strikethrough | `~strikethrough~` |
-| Code | `` `inline code` `` |
-| Code block | ` ```code block``` ` |
-| Link | `<https://example.com|Display Text>` |
-| User mention | `<@U12345>` |
-| Channel mention | `<#C12345>` |
-| Emoji | `:emoji_name:` |
-| Blockquote | `> quoted text` |
-| List | `• item` or `1. item` |
-
 ## Rate Limits
 
-| Tier | Limit | Applies to |
-|------|-------|------------|
-| Tier 1 | 1 per minute | Rare admin actions |
-| Tier 2 | 20 per minute | Most write operations (`chat:write`) |
-| Tier 3 | 50 per minute | Most read operations |
-| Tier 4 | 100+ per minute | Search, history reads |
-
-**Best practices:**
+Write ops are Tier 2 (20/min); read ops Tier 3 (50/min). Best practices:
 - Batch updates into single messages rather than posting many small messages
 - Use threads to consolidate related updates
-- Add 1-second delays between consecutive write operations
 - Cache channel/user IDs — don't look them up repeatedly
 
 ## Security Considerations
 
-- **Bot tokens** are passed via `SLACK_MCP_XOXB_TOKEN` env var (in `.env` file) — never hardcode in config files or commit to git
-- **Scope minimization** — request only the scopes agents actually need (omit `channels:manage` if agents shouldn't create channels)
-- **Channel restrictions** — limit the bot to specific channels rather than granting workspace-wide access
-- **Audit logging** — Slack Enterprise Grid provides audit logs for all API activity
-- **No secrets in messages** — never post tokens, passwords, or credentials in Slack messages (per Constitution #1)
-
-## Integration with Agent Workflows
-
-### Session Start
-
-At the beginning of a work session, post a brief status message:
-```
-🏁 **Session started**
-Agent: Frontend Engineer
-Task: TAS-42 — Add price filter component
-Mode: Autonomous (will request approval for destructive actions)
-```
-
-### Session End
-
-At the end of a work session, post a summary:
-```
-🏁 **Session complete**
-Agent: Frontend Engineer
-Task: TAS-42 — Add price filter component
-Result: ✅ PR opened (#123)
-Duration: 12 minutes
-Files changed: 5
-Tests: 12 passing, 0 failing
-```
-
-### Error Recovery
-
-If an agent encounters an unrecoverable error, notify before stopping:
-```
-💥 **Session failed**
-Agent: Frontend Engineer
-Task: TAS-42 — Add price filter component
-Error: TypeScript compilation failed — 3 type errors in PriceFilter.tsx
-Action: Posted details in thread. Needs manual fix or re-delegation.
-```
+- **Bot tokens** are passed via `SLACK_MCP_XOXB_TOKEN` env var — never hardcode in config files or commit to git
+- **Scope minimization** — request only the scopes agents actually need
+- **No secrets in messages** — never post tokens, passwords, or credentials in Slack messages