opencastle 0.32.12 → 0.33.0

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

@@ -0,0 +1,24 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Slack REFERENCE: authentication scopes, token setup, and MCP server environment variables.
+
+Move security and auth details here to keep `SKILL.md` concise.
+Last Updated: 2026-03-31
+
+Reference: Slack scopes & MCP tools
+
+## OAuth Scopes (recommended minimal sets)
+
+- Bot (notifications): `chat:write`, `channels:read`, `conversations:history`, `users:read`
+- Read-only: `channels:read`, `channels:history`, `im:read`
+
+## MCP Tools (compact)
+
+- `conversations_add_message` — `channel_id`, `payload`, `content_type`, `thread_ts`
+- `conversations_history` — `channel_id`, `limit`
+- `conversations_replies` — `channel_id`, `thread_ts`, `limit`
+- `users_resolve` — `email|username`
+
+## Token handling
+
+- Store `SLACK_MCP_XOXB_TOKEN` in CI/env; rotate periodically; log token rotations in the observability log.

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

@@ -7,145 +7,70 @@ description: "Slack MCP integration for agent-to-human notifications and bi-dire
 
 # Slack Notifications
 
-Agent communication patterns via the Slack MCP server. Enables agents to post progress updates, request human approvals, and read responses — all through Slack channels and threads.
-
 ## MCP Server
 
-| Field | Value |
-|-------|-------|
-| **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 |
-| **Extra env** | `SLACK_MCP_ADD_MESSAGE_TOOL=true` — enables `conversations_add_message` |
-
-### Authentication
-
-Use a **bot token** (`SLACK_MCP_XOXB_TOKEN`). For message search, a user token (`xoxp-…`) via `SLACK_MCP_XOXP_TOKEN` is required instead.
-
-**Bot Token Scopes:**
-
-| Scope | Purpose |
-|-------|---------|
-| `chat:write` | Post messages and replies |
-| `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
-
-### Channel Management
-
-`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`, `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
-
-`users_resolve` — look up a user by name or email; returns user ID for mentions.
+Package: `@kazuph/mcp-slack` (stdio). Auth: `SLACK_MCP_XOXB_TOKEN` env var. Enable `SLACK_MCP_ADD_MESSAGE_TOOL=true`.
 
-### 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 or canvas tools available via this MCP server
+See [REFERENCE.md](REFERENCE.md) for OAuth scopes and token setup.
 
 ## Agent Notification Patterns
 
 ### Progress Updates
 
 ```
-Channel: #agent-updates (or project-specific channel)
-Format:
-  🔄 **Task:** TAS-42 — Add price filter component
-  **Status:** In progress — implementing unit tests
-  **Files changed:** 3 (PriceFilter.tsx, PriceFilter.test.tsx, index.ts)
-  **ETA:** ~5 minutes
+🔄 TAS-42 — In progress — implementing unit tests
+Files: 3 (PriceFilter.tsx, test, index) | ETA: ~5 min
 ```
 
-## Bi-Directional Communication
-
-### Dual-Channel Approval Pattern
+### MCP invocation example
 
-Approval requests are always **dual-channel** — posted to Slack AND asked in the chat window. The first response wins.
+Post an approval request:
 
+```js
+const res = mcp_slack_conversations_add_message({
+  channel: 'C012345',
+  text: '⏳ Approval Required — TAS-42: Run DB migration?',
+  thread_ts: null
+});
+if (!res?.ok) throw new Error('Slack post failed: ' + res?.error);
 ```
-Agent needs approval
- ├─→ Posts to Slack channel/thread
- │     → User replies in Slack
- │     → Agent polls & picks it up ──────┐
- │                                       ▼
- │                                  Agent acts
- │                                       ▲
- └─→ Asks in VS Code chat                │
-       → User replies here ──────────────┘
-       (immediate, no polling needed)
-```
 
-### Approval Flow
+## Bi-Directional Communication
+
+Approval requests are **dual-channel** — post to Slack AND ask in chat. First response wins.
 
-1. **Post to Slack** with a structured approval request:
+1. **Post to Slack:**
    ```
-   ⏳ **Approval Required**
-   Task: TAS-42 — Database migration adds `price_range` column
-   Action: Run migration on production database
-
-   Reply in this thread with:
-   ✅ "approved" — Approve and proceed
-   ❌ "rejected" — Reject and stop
-   💬 Or reply with questions
+   ⏳ Approval Required — TAS-42: Run DB migration
+   Reply: ✅ approved | ❌ rejected | 💬 questions
    ```
 
-2. **Ask in chat** — Yield to the user with the same question so they can respond directly.
+2. **Ask in chat** with the same question.
 
-3. **If the user responds in chat** — Post confirmation to the Slack thread: `✅ Approved via VS Code chat. Proceeding.`
+3. **Chat response wins** → post confirmation to Slack thread.
 
-4. **If waiting for Slack reply** — Poll every 30 seconds using `conversations_replies` with the message's `thread_ts`. Continue independent subtasks between polls.
+4. **Waiting for Slack** → poll thread:
 
-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
-
-| Signal | Meaning |
-|--------|---------|
-| Thread reply with "approved" / "yes" / "go" | Approved — proceed |
-| Thread reply with "rejected" / "no" / "stop" | Rejected — stop and report |
-| Thread reply with "reviewing" / "looking" | Acknowledged — user is reviewing |
-| Thread reply with detailed text | Instructions or questions |
-| `@agent` mention | Direct command or question for the agent |
+```js
+// Poll for approval reply (30s interval, 10 min timeout)
+const replies = mcp_slack_conversations_replies({ channel: 'C012345', ts: threadTs, limit: 20 });
+for (const msg of replies?.messages || []) {
+  if (/\b(approved|yes|go)\b/i.test(msg.text)) return 'approved';
+  if (/\b(rejected|no|stop)\b/i.test(msg.text)) return 'rejected';
+}
+// Retry after 30s; timeout after 10 min
+```
 
-> **Note:** Reactions are not available via the Slack MCP server. Use thread replies for all approval workflows.
+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.
 
-## Channel & Thread Conventions
 
-Project-specific channel mappings are defined in `.opencastle/stack/notifications-config.md`. Always prefer channel IDs from the config over hardcoded names.
 
-### Threading Rules
+## Conventions
 
-- **Always thread replies** — never post top-level messages for follow-ups
-- **One thread per task** — keep all updates for a single task in one thread
-- **Include task ID** — every message references the tracker issue ID
-- **Pin important threads** — pin approval requests and blocking issues
+Project-specific channel mappings: `.opencastle/stack/notifications-config.md`. Always thread replies; one thread per task; include tracker issue ID.
 
 ## Rate Limits
 
-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
-- Cache channel/user IDs — don't look them up repeatedly
-
-## Security Considerations
+Write: 20/min; Read: 50/min. Batch updates; use threads; cache channel/user IDs.
 
-- **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
+See [REFERENCE.md](REFERENCE.md) for security guidelines.

package/src/orchestrator/plugins/strapi/REFERENCE.md

@@ -0,0 +1,35 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Strapi Reference: GraphQL & Plugin Development
+
+### GraphQL Plugin
+
+- Enable via `@strapi/plugin-graphql`.
+- Auto-generates types and resolvers from content types; use `filters`, `pagination`, and `sort` arguments.
+- Custom resolvers live under `src/api/<type>/graphql/` — keep GraphQL-specific transformations isolated.
+
+### Plugin Development
+
+- Scaffold with `strapi generate plugin <name>`.
+- Plugin structure: `admin/`, `server/`, `content-types/` — register in `config/plugins.ts`.
+- Use the Plugin SDK for admin panel extensions and keep server logic under `server/` to avoid bundling admin code.
+# Strapi Reference (REFERENCE.md)
+
+Last Updated: 2026-03-31
+
+## Populate & filters quick reference
+
+- Populate relations: `?populate=author,categories` or deep `?populate=deep` for all relations.
+- Filters example: `?filters[status][$eq]=published&filters[views][$gte]=100`
+- Fields selection: `?fields[0]=title&fields[1]=slug`
+
+## Common API patterns
+
+- Paginated list with relations: `/api/articles?populate=author,categories&pagination[page]=1&pagination[pageSize]=10`
+- Single entry by slug: `/api/articles?filters[slug][$eq]=my-post&populate=author`
+
+## Recommended tests
+
+1. Endpoint smoke test: GET `/api/<type>?pagination[page]=1` returns 200 and `data` array.
+2. Relation test: GET with `populate` returns `relationships` with expected keys.
+3. Permission test: verify `public` role returns 200/403 as configured.

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

@@ -1,6 +1,6 @@
 ---
 name: strapi-cms
-description: "Strapi CMS development patterns, REST/GraphQL API usage, content type building, plugin development, and deployment best practices. Use when working with Strapi content types, controllers, services, or plugins."
+description: "Builds Strapi content types, extends controllers and services, implements lifecycle hooks, and configures REST/GraphQL APIs. Use when creating content types, writing custom controllers, developing Strapi plugins, or querying the API."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -13,33 +13,69 @@ Generic Strapi CMS development methodology. For project-specific configuration,
 
 1. **Use Content-Type Builder** — define content types through the admin panel or `content-types` directory
 2. **REST API by default** — Strapi exposes REST endpoints automatically; enable GraphQL plugin if needed
-3. **Customize controllers** — extend auto-generated controllers in `src/api/<type>/controllers/`
-4. **Services for business logic** — keep business logic in services, not controllers
-5. **Lifecycle hooks** — use model lifecycle hooks for side effects (e.g., `beforeCreate`, `afterUpdate`)
-6. **Permissions and roles** — configure permissions via the Users & Permissions plugin
-7. **Draft/Publish system** — enable draft/publish on content types that need editorial workflow
-8. **Media Library** — use Strapi's media library for asset management; configure providers for S3/Cloudinary
-9. **Environment configs** — use `config/env/<env>/` for environment-specific configuration
-10. **Never modify `node_modules`** — extend functionality through plugins and customizations
+3. **Extend controllers** — implement `src/api/<type>/controllers/<type>.js` with wrapper logic that calls services
+4. **Implement services** — place business logic in `src/api/<type>/services/` and keep controllers thin
+5. **Use lifecycle hooks** — add `beforeCreate`/`afterUpdate` handlers in `src/api/<type>/lifecycles.js` for side effects
+6. **Configure permissions per role** — set public/authenticated access in Users & Permissions; keep environment configs under `config/env/<env>/`
 
 ## API Patterns
 
-### REST API
-- Endpoints follow `/api/<content-type>` convention
-- Use `populate` parameter to include relations
-- Use `filters` parameter with operators (`$eq`, `$contains`, `$in`, etc.)
+### REST API (Strapi-specific)
+- Use `populate` to include relations
+- Use `filters` with operators (`$eq`, `$contains`, `$in`, etc.)
 - Pagination via `pagination[page]` and `pagination[pageSize]`
-- Use `fields` to select specific attributes
+- Use `fields` to select attributes
 
-### GraphQL Plugin
-- Enable via `@strapi/plugin-graphql`
-- Auto-generates types and resolvers from content types
-- Use `filters`, `pagination`, and `sort` arguments
-- Custom resolvers in `src/api/<type>/graphql/`
+### Quick REST examples
 
-## Plugin Development
+GET with populate and filters (client-side fetch):
 
-- Scaffold with `strapi generate plugin <name>`
-- Follow the plugin structure: `admin/`, `server/`, `content-types/`
-- Register plugin in `config/plugins.ts`
-- Use the Plugin SDK for admin panel extensions
+```js
+// GET /api/articles?populate=author,categories&filters[status][$eq]=published&pagination[page]=1&pagination[pageSize]=10
+const res = await fetch('https://cms.example.com/api/articles?populate=author,categories&filters[status][$eq]=published');
+const json = await res.json();
+console.log(json.data[0].attributes.title);
+```
+
+Custom controller extension (server):
+
+```js
+// src/api/article/controllers/article.js
+const { createCoreController } = require('@strapi/strapi').factories;
+
+module.exports = createCoreController('api::article.article', ({ strapi }) => ({
+	async find(ctx) {
+		// call default then modify response
+		const res = await super.find(ctx);
+		// add extra field
+		res.meta.custom = { processedAt: new Date().toISOString() };
+		return res;
+	},
+}));
+```
+
+Lifecycle hook example:
+
+```js
+// src/api/article/content-types/article/lifecycles.js
+module.exports = {
+	async beforeCreate(event) {
+		const { data } = event.params;
+		if (data.title) data.slug = slugify(data.title);
+	},
+};
+```
+
+
+## Quick workflow: create content type + custom controller + service
+
+1. Create content type using Content-Type Builder or `src/api/<type>/content-types/schema.json` → commit schema.
+2. Scaffold controller and service files under `src/api/<type>/controllers/` and `src/api/<type>/services/` with thin controller calling service functions.
+3. Add lifecycle hooks (optional) in `content-types/<type>/lifecycles.js` for side effects.
+4. Run local Strapi (`yarn develop`) → check admin UI for new content type.
+	- Validation: create a test entry in admin UI and confirm via `GET /api/<type>?pagination[page]=1` that fields exist.
+	- If fail: check server logs, run `yarn build` to surface schema errors, verify `schema.json` validity.
+5. Add permissions (Users & Permissions) for public/authenticated roles if API access required.
+6. Add automated API test: `fetch('/api/<type>?populate=*')` in test suite to validate relations populate.
+
+For more reference patterns and larger examples, see [REFERENCE.md](REFERENCE.md).

package/src/orchestrator/plugins/supabase/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Supabase migrations & RLS tests
+
+- CI snippets for applying migrations and generating TypeScript types
+- Example RLS test queries for `anon`, `user`, and `admin` roles
+- Backfill and phased-migration strategies for destructive changes

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

@@ -1,6 +1,6 @@
 ---
 name: supabase-database
-description: "Supabase database migration rules, RLS policy patterns, and auth integration best practices. Use when designing database tables, writing migrations, configuring RLS policies, implementing auth, or managing user roles."
+description: "Generates Supabase database migrations, writes RLS policies with auth.uid(), configures auth integration, and generates TypeScript types. Use when creating tables, writing migrations, configuring RLS, or implementing Supabase auth."
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
@@ -9,18 +9,46 @@ description: "Supabase database migration rules, RLS policy patterns, and auth i
 
 Generic Supabase development methodology. For project-specific schema, roles, migration history, auth flow, and key files, see [supabase-config.md](../../.opencastle/stack/supabase-config.md).
 
-## Migration Rules
-
-1. Always write migrations for schema changes — never modify schema directly.
-2. Use RLS on all tables — no exceptions.
-3. Test RLS from different roles (anon, user, moderator, admin).
-4. `CASCADE DELETE` where appropriate.
-5. Add indexes for frequently queried columns.
-6. Naming: `NNN_description.sql` or `YYYYMMDD_description.sql`.
-7. Write idempotent migrations — they must be safe to re-run.
-8. Document migration purpose with SQL comments.
-9. Validate schema changes don't break existing RLS policies.
-10. Use `auth.uid()` in RLS policies — never pass user ID from the client.
-11. Prefer database functions for complex authorization logic.
-12. Test migrations in a development dataset before production.
-13. Always generate TypeScript types after schema changes.
+## Migration Rules (sequential workflow)
+
+1. Plan: create a migration with a descriptive name (`YYYYMMDD_add_profiles.sql`) and list expected schema changes.  
+2. Author: write the SQL migration and include inline comments describing intent and rollback considerations.  
+3. Local validate: apply the migration to a local or ephemeral DB; run smoke tests and verify RLS policies for `anon`, `user`, and `admin`.  
+4. Inspect: review generated SQL for destructive actions (table drops, column rewrites). If destructive, add backfill scripts and phased changes.  
+5. CI verify: run the migration in CI against a test replica and run the full test suite.  
+6. Deploy: promote migration to production using the project's safe-deploy pipeline.  
+7. Post-check: verify row-level security, indexes, and perform a small data validation query.
+
+Validation checkpoints: after steps 3 and 5 assert (a) migration completes, (b) RLS policies still pass for role-specific queries, (c) tests covering changed paths pass. On failure: revert, adjust migration, and re-run.
+
+## Migration Example (consolidated)
+
+```sql
+-- 20260331_create_profiles.sql
+CREATE TABLE IF NOT EXISTS public.profiles (
+  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
+  display_name TEXT NOT NULL,
+  avatar_url TEXT,
+  created_at TIMESTAMPTZ DEFAULT now()
+);
+
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+
+-- RLS: Users can read all profiles, update only their own
+CREATE POLICY "Profiles are viewable by everyone"
+  ON public.profiles FOR SELECT USING (true);
+CREATE POLICY "Users can update own profile"
+  ON public.profiles FOR UPDATE USING (auth.uid() = id);
+CREATE POLICY "Users can insert own profile"
+  ON public.profiles FOR INSERT WITH CHECK (auth.uid() = id);
+
+-- Type generation (CI):
+-- supabase gen types typescript --project-id <project-id> > src/types/supabase.ts
+```
+
+## Verification
+
+```sql
+-- Confirm RLS is enabled on all tables
+SELECT tablename, rowsecurity FROM pg_tables WHERE schemaname = 'public';
+```

package/src/orchestrator/plugins/teams/REFERENCE.md

@@ -0,0 +1,36 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+# Teams Reference (REFERENCE.md)
+
+Last Updated: 2026-03-31
+
+## Adaptive Cards
+
+Use this file for canonical Adaptive Card payloads used by approval workflows.
+
+Example Approval card (structured submit):
+
+```json
+{
+  "type": "AdaptiveCard",
+  "body": [
+    { "type": "TextBlock", "text": "Approval Required", "weight": "Bolder", "size": "Medium" },
+    { "type": "TextBlock", "text": "Task: <ID> — <Short description>", "wrap": true }
+  ],
+  "actions": [
+    { "type": "Action.Submit", "title": "Approve", "data": { "action": "approve" } },
+    { "type": "Action.Submit", "title": "Reject", "data": { "action": "reject" } }
+  ],
+  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+  "version": "1.4"
+}
+```
+
+## Rate Limits
+
+- Graph API suggestions: cache IDs, batch messages, and avoid per-user repeated lookups. Specific tenant limits may vary.
+
+## Security Notes
+
+- Keep scopes minimal. If the integration needs approve/reject, delegated user consent is preferable to application-level broad scopes.
+- Never include secrets in message bodies. Use the MCP server to mediate tokens.

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

@@ -7,115 +7,65 @@ description: "Microsoft Teams MCP integration for agent-to-human notifications a
 
 # Teams Notifications
 
-Agent communication patterns via the Microsoft Teams MCP server (Microsoft Agent 365). Enables agents to post progress updates, request human approvals, and read responses — all through Teams channels and chats.
-
 ## MCP Server
 
-| Field | Value |
-|-------|-------|
-| **URL** | `https://mcp.microsoft365.com/mcp` |
-| **Type** | Remote MCP server (HTTP) |
-| **Auth** | Microsoft Graph API — OAuth 2.0 with `McpServers.Teams.All` scope |
-| **Platform** | Microsoft Agent 365 (Frontier preview) |
-| **Status** | Preview — requires Microsoft Agent 365 Frontier preview access |
+URL: `https://mcp.microsoft365.com/mcp`. Auth: OAuth 2.0 (Azure AD, scopes: `Chat.ReadWrite`, `ChannelMessage.Send`).
 
-### Prerequisites
+## MCP Tools
 
-1. **Microsoft Agent 365 Frontier preview** enrollment
-2. **App registration** in Microsoft Entra ID (Azure AD)
-3. **Graph API permissions:** `McpServers.Teams.All` (delegated or application)
-4. **Admin consent** for the registered app
+Covers chats, messages, channels, members, and settings.
 
-## Available MCP Tools
+### Example MCP calls
 
-Tool names follow `teams_<resource>_<action>`. Covers: chats, messages, channels, members, and team settings. Use tool discovery to list available tools at runtime.
+Post a progress update:
 
-## Agent Notification Patterns
+```json
+// tool: teams_messages_create
+{ "channel_id": "channel-xyz", "body": "🔄 TAS-42 — In progress — implementing unit tests\nFiles: 3 (PriceFilter.tsx, test, index)" }
+```
 
-### Progress Updates
+Read replies in thread:
 
-```
-Channel: Agent Updates (or project-specific channel)
-Format:
-  🔄 **Task:** TAS-42 — Add price filter component
-  **Status:** In progress — implementing unit tests
-  **Files changed:** 3 (PriceFilter.tsx, PriceFilter.test.tsx, index.ts)
-  **ETA:** ~5 minutes
+```json
+// tool: teams_messages_list_replies
+{ "channel_id": "channel-xyz", "thread_id": "thread-abc", "limit": 50 }
 ```
 
 ## Human-in-the-Loop Approval
 
-1. **Post approval request** to the channel:
-   ```
-   ⏳ **Approval Required**
-   Task: TAS-42 — Database migration adds `price_range` column
-   Action: Run migration on production database
-
-   Reply with:
-   ✅ Approve — to proceed
-   ❌ Reject — to stop
-   Or reply with questions/comments
-   ```
-2. **Poll for response** — Read replies to determine the decision.
-3. **Acknowledge** — Post confirmation of the action taken.
-
-### Parsing Conventions
-
-| Signal | Meaning |
-|--------|---------|
-| `✅` or "approve"/"yes" reply | Approved — proceed |
-| `❌` or "reject"/"no" reply | Rejected — stop and report |
-| `👀` reaction or "looking" reply | Acknowledged — user is reviewing |
-| Detailed reply | Instructions or questions for the agent |
-| `@mention` of agent | Direct command or question |
-
-## Channel & Chat Conventions
-
-### Threading Rules
-
-- **Always reply in threads** — use message replies, not top-level posts for follow-ups
-- **One thread per task** — keep all updates for a single task in one conversation thread
-- **Include task ID** — every message references the tracker issue ID
-- **Mark important messages** — use importance flags for approval requests
+1. **Post approval request** — verify the response confirms message_id:
 
-## Message Formatting
+```json
+// tool: teams_messages_create
+{ "channel_id": "channel-xyz", "body": "⏳ Approval Required\nTask: TAS-42 — Run migration on production\nReply: Approve or Reject", "threading": { "start_thread": true } }
+// → { "message_id": "msg-123", "thread_id": "thread-abc" }
+```
 
-### Adaptive Cards
+   If post fails: retry once; if still failing, fall back to asking in chat only.
 
-For richer formatting, use Adaptive Cards (JSON-based):
+2. **Poll for response** (5s interval, 5 min timeout):
 
-```json
-{
-  "type": "AdaptiveCard",
-  "body": [
-    { "type": "TextBlock", "text": "Approval Required", "weight": "Bolder", "size": "Medium" },
-    { "type": "TextBlock", "text": "Task: TAS-42 — Database migration", "wrap": true }
-  ],
-  "actions": [
-    { "type": "Action.Submit", "title": "Approve", "data": { "action": "approve" } },
-    { "type": "Action.Submit", "title": "Reject", "data": { "action": "reject" } }
-  ],
-  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
-  "version": "1.4"
+```js
+const replies = await teams_messages_list_replies({ channel_id: channelId, thread_id: threadId, limit: 50 });
+for (const r of replies || []) {
+  if (/\b(approve|yes)\b/i.test(r.body)) return 'approved';
+  if (/\b(reject|no)\b/i.test(r.body)) return 'rejected';
 }
+// Retry after 5s; timeout after 5 min → post escalation message
 ```
 
-Use Adaptive Cards for approval workflows when available — they provide structured input.
+3. **Acknowledge** — Post confirmation of the action taken and close the thread.
 
-## Rate Limits
 
-Microsoft Graph API: 50 messages/second per app per tenant; 10,000 individual API calls per 10 minutes.
 
-**Best practices:**
-- Batch updates into single messages rather than posting many small messages
-- Cache team/channel/user IDs — don't look them up repeatedly
+## Channel & Chat Conventions
+
+### Threading Rules
 
-## Security Considerations
+- Always reply in threads; one thread per task; include tracker issue ID in every message.
 
-- **OAuth tokens** are managed by the MCP server — agents never see raw tokens
-- **Scope minimization** — request only the Graph API permissions agents actually need
-- **No secrets in messages** — never post tokens, passwords, or credentials in Teams messages
+## Message Formatting
 
-## Preview Limitations
+### Adaptive Cards and advanced payloads
 
-The Teams MCP server is in Frontier preview — availability and tool surface may change without notice. Check [Microsoft Agent 365 documentation](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/) for the latest status.
+For large Adaptive Card JSON, rate limits, and security considerations see [REFERENCE.md](REFERENCE.md). Use Adaptive Cards when structured inputs or buttons are required; otherwise post a simple threaded message.

package/src/orchestrator/plugins/trello/REFERENCE.md

@@ -0,0 +1,9 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Last Updated: 2026-03-31
+
+Reference: Trello MCP tool details
+
+- Full MCP tool parameter table and example calls (`get_boards`, `get_lists`, `create_card`, `update_card`).
+- Example scripts for adding checklists and migrating cards between lists.
+- Auth token troubleshooting and token rotation guidance.