opencastle 0.3.2 → 0.4.0

package/src/orchestrator/agents/release-manager.agent.md

@@ -2,7 +2,7 @@
 description: 'Release manager for pre-release verification, changelog generation, version management, regression checks, and release coordination.'
 name: 'Release Manager'
 model: GPT-5.3-Codex
-tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'vercel/get_deployment', 'vercel/get_deployment_build_logs', 'vercel/get_runtime_logs', 'vercel/list_deployments', 'vercel/list_projects', 'nx-mcp-server/nx_project_details', 'nx-mcp-server/nx_workspace', 'nx-mcp-server/nx_workspace_path']
+tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'web/fetch', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'search', 'execute/testFailure', 'search/usages', 'vercel/get_deployment', 'vercel/get_deployment_build_logs', 'vercel/get_runtime_logs', 'vercel/list_deployments', 'vercel/list_projects', 'nx-mcp-server/nx_project_details', 'nx-mcp-server/nx_workspace', 'nx-mcp-server/nx_workspace_path', 'slack/*']
 ---
 
 <!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the customizations/ directory instead. -->

package/src/orchestrator/agents/team-lead.agent.md

@@ -2,7 +2,7 @@
 description: 'Task orchestrator that analyzes work, decomposes it into subtasks, and delegates to specialized agents via sub-agents (inline) or background sessions (parallel worktrees).'
 name: 'Team Lead'
 model: Claude Opus 4.6
-tools: [read/problems, read/readFile, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/searchResults, search/textSearch, search/usages, web/fetch, agent, execute/runInTerminal, execute/getTerminalOutput, read/terminalLastCommand, read/terminalSelection, linear/create_issue, linear/get_issue, linear/list_issues, linear/list_projects, linear/list_teams, linear/search_issues, linear/update_issue]
+tools: [read/problems, read/readFile, agent/runSubagent, edit/createDirectory, edit/createFile, edit/createJupyterNotebook, edit/editFiles, edit/editNotebook, search/changes, search/codebase, search/fileSearch, search/listDirectory, search/searchResults, search/textSearch, search/usages, web/fetch, agent, execute/runInTerminal, execute/getTerminalOutput, read/terminalLastCommand, read/terminalSelection, linear/create_issue, linear/get_issue, linear/list_issues, linear/list_projects, linear/list_teams, linear/search_issues, linear/update_issue, slack/*]
 agents: ['*']
 handoffs:
   - label: Implement Feature
@@ -594,6 +594,8 @@ When multiple agents complete work simultaneously, batch similar reviews. Load *
 - [ ] All Linear issues moved to Done
 - [ ] Lint, test, and build pass for affected projects
 - [ ] Documentation updated
+- [ ] **Session records logged** to `.github/customizations/logs/sessions.ndjson` — one entry per completed task
+- [ ] **Delegation records logged** to `.github/customizations/logs/delegations.ndjson` — one entry per delegation
 - [ ] All changes committed to the feature branch with Linear issue IDs in commit messages
 - [ ] Branch pushed to origin
 - [ ] PR opened on GitHub (NOT merged)
@@ -618,6 +620,15 @@ Track failed agent delegations in `.github/customizations/AGENT-FAILURES.md` so
 
 When automated resolution is exhausted (panel 3x BLOCK, unresolvable conflicts), create a **formal dispute record** in `.github/customizations/DISPUTES.md` instead. Disputes package both perspectives, attempt history, and resolution options — giving humans a clear, actionable decision rather than a raw failure log. See the **team-lead-reference** skill § Dispute Protocol for the full procedure.
 
+## Observability Logging
+
+**The Team Lead MUST log every session.** No exceptions. See `general.instructions.md` § Observability Logging for the full rules.
+
+- After delegations: log a **session record** + a **delegation record**
+- After working directly: log a **session record** (use the matching agent role)
+- Log **per task**, before yielding to the user
+- Multiple tasks in one conversation = multiple records
+
 ## Anti-Patterns
 
 - **Never write or delegate code before Linear issues exist** — issues are a blocking gate, not a follow-up task
@@ -644,3 +655,4 @@ When automated resolution is exhausted (panel 3x BLOCK, unresolvable conflicts),
 - **Never merge a PR yourself** — PRs are opened for human review only
 - **Never forget to link the PR to Linear** — traceability is mandatory
 - **Never exceed session budget without checkpointing** — context degrades after 8+ delegations; save state and resume in a fresh session
+- **Never skip observability logging** — every session gets logged. No exceptions. No threshold. No "too small to log"

package/src/orchestrator/customizations/stack/notifications-config.md

@@ -0,0 +1,57 @@
+# Notifications Configuration
+
+<!-- Populated by the `bootstrap-customizations` prompt based on `.opencastle.json` → `stack.notifications`. -->
+
+Project-specific messaging configuration referenced by the `slack-notifications` skill (or Teams equivalent).
+
+## Provider
+
+<!-- Which messaging provider is configured: slack, teams, or none -->
+
+| Field | Value |
+|-------|-------|
+| **Provider** | <!-- slack / teams / none --> |
+| **MCP Server** | <!-- e.g., @kazuph/mcp-slack --> |
+| **Bot Name** | <!-- e.g., OpenCastle Agents --> |
+
+## Channels
+
+Map project channels to their purpose. Agents use this table to determine where to post.
+
+| Channel Name | Channel ID | Purpose |
+|-------------|------------|---------|
+| <!-- e.g., #agent-updates --> | <!-- e.g., C0AHAQFJ7C1 --> | <!-- General agent activity feed --> |
+| <!-- e.g., #agent-approvals --> | <!-- e.g., C0BHKL3M2D4 --> | <!-- Approval requests requiring human action --> |
+| <!-- e.g., #agent-errors --> | <!-- e.g., C0CJNM4P5E6 --> | <!-- Error reports and blocked tasks --> |
+
+> **Tip:** Use `channels_list` via MCP to discover channel IDs, then populate this table.
+
+## Notification Preferences
+
+Configure which events trigger notifications and where they go.
+
+| Event | Channel | Enabled |
+|-------|---------|---------|
+| Task started | <!-- #agent-updates --> | <!-- yes/no --> |
+| Task completed | <!-- #agent-updates --> | <!-- yes/no --> |
+| Approval needed | <!-- #agent-approvals --> | <!-- yes/no --> |
+| Error / blocked | <!-- #agent-errors --> | <!-- yes/no --> |
+| Session started | <!-- #agent-updates --> | <!-- yes/no --> |
+| Session ended | <!-- #agent-updates --> | <!-- yes/no --> |
+
+## Users
+
+Map team members to their messaging user IDs for mentions.
+
+| Name | User ID | Role |
+|------|---------|------|
+| <!-- e.g., Filip --> | <!-- e.g., U0AJ7DL9KS5 --> | <!-- e.g., Project Lead --> |
+
+> **Tip:** Use `users_resolve` via MCP to look up user IDs by name or email.
+
+## Environment Variables
+
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `SLACK_MCP_XOXB_TOKEN` | Bot token for Slack MCP server | Yes (if provider is Slack) |
+| `SLACK_MCP_ADD_MESSAGE_TOOL` | Enable message posting (`true` or comma-separated channel IDs) | Yes (if agents should post) |

package/src/orchestrator/instructions/general.instructions.md

@@ -153,6 +153,34 @@ If Linear MCP tools are not available in the current session, do NOT block on is
 4. **Ask the user** to create the issues manually if tracking is critical for the task
 5. After implementation, update commit messages and PR descriptions when issue IDs become available
 
+## Observability Logging (Mandatory)
+
+**Every agent MUST log every session to the observability NDJSON files.** No exceptions. No threshold. No "too small to log." The dashboard depends on this data.
+
+### What to log
+
+| File | Who appends | When |
+|------|------------|------|
+| `sessions.ndjson` | **All agents** | After every session — always |
+| `delegations.ndjson` | **Team Lead** | After each delegation to a specialist agent |
+| `panels.ndjson` | **Panel runner** | After each majority-vote review |
+
+See `.github/customizations/logs/README.md` for the full schema of each record.
+
+### How to log
+
+Append one JSON line per task. When the Team Lead works directly, use the agent role that best describes the work (e.g., `"agent": "Developer"`, `"agent": "UI-UX Expert"`). If a single conversation involves multiple distinct tasks, log one record per task.
+
+```bash
+echo '{"timestamp":"2026-03-01T14:00:00Z","agent":"Developer","model":"claude-opus-4-6","task":"Fix login redirect bug","outcome":"success","duration_min":15,"files_changed":3,"retries":0,"lessons_added":[],"discoveries":[]}' >> .github/customizations/logs/sessions.ndjson
+```
+
+### Rules
+
+- **Log before yielding to the user** — logging is the last action before responding.
+- **Log per task**, not per conversation. Multiple tasks = multiple records.
+- **Never batch-log retrospectively** across sessions.
+
 ## Self-Improvement Protocol
 
 **Every agent must learn from mistakes and share knowledge.** This prevents the same pitfalls from being repeated across sessions.
@@ -160,7 +188,6 @@ If Linear MCP tools are not available in the current session, do NOT block on is
 1. **Before starting work:** Read `.github/customizations/LESSONS-LEARNED.md` — apply relevant lessons proactively
 2. **During execution:** If you retry a command/tool with a different approach and it works, **immediately** add a lesson entry to `.github/customizations/LESSONS-LEARNED.md`
 3. **Update source files:** If the lesson reveals a gap in instruction/skill files, update those files too
-5. **Log the session:** Append a JSON line to `.github/customizations/logs/sessions.ndjson` when your work is complete — see `.github/customizations/logs/README.md` for the schema
 4. **Update instructions:** Proactively suggest updates to `.github/instructions/` or `.github/skills/` files when:
    - The user had to intervene or correct the agent's approach
    - Multiple back-and-forth attempts were needed to get something right
@@ -183,11 +210,13 @@ These rules apply to ALL specialist agents automatically. **Do not duplicate the
 1. **Never delegate** — Specialist agents complete their own work and return results. Never invoke the Team Lead or spawn sub-agents. If work requires another domain, document the need in your output contract.
 2. **Follow the Discovered Issues Policy** — Track any pre-existing bugs found during your work (see § Discovered Issues Policy above).
 3. **Read and update lessons** — Read `.github/customizations/LESSONS-LEARNED.md` before starting. If you retry anything with a different approach that works, add a lesson immediately.
+4. **Log every session** — Append to `.github/customizations/logs/sessions.ndjson` after every session. No exceptions. See § Observability Logging above.
 
 ## Base Output Contract
 
-Every specialist agent's Output Contract MUST end with these two standard items (in addition to domain-specific items above them):
+Every specialist agent's Output Contract MUST end with these standard items (in addition to domain-specific items above them):
 
+- **Session Logged** — Confirm that a session record was appended to `.github/customizations/logs/sessions.ndjson` (mandatory per § Observability Logging)
 - **Discovered Issues** — Pre-existing bugs or anomalies found during work, with tracking action taken per the Discovered Issues Policy
 - **Lessons Applied** — Lessons from `.github/customizations/LESSONS-LEARNED.md` that influenced this work, and any new lessons added
 

package/src/orchestrator/mcp.json

@@ -34,18 +34,24 @@
     "Linear": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@mseep/linear-mcp"],
-      "env": {
-        "LINEAR_API_KEY": "${env:LINEAR_API_KEY}"
-      }
+      "args": [
+        "-y",
+        "@mseep/linear-mcp"
+      ],
+      "envFile": "${workspaceFolder}/.env"
     },
     "Jira": {
       "url": "https://mcp.atlassian.com/v2/sse",
       "type": "http"
     },
     "Slack": {
-      "url": "https://mcp.slack.com/mcp",
-      "type": "http"
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@kazuph/mcp-slack"],
+      "envFile": "${workspaceFolder}/.env",
+      "env": {
+        "SLACK_MCP_ADD_MESSAGE_TOOL": "true"
+      }
     },
     "Teams": {
       "url": "https://mcp.microsoft365.com/mcp",

package/src/orchestrator/skills/agent-hooks/SKILL.md

@@ -30,8 +30,9 @@ Session Lifecycle:
 
 1. **Read lessons learned** — Scan `.github/customizations/LESSONS-LEARNED.md` for entries relevant to the current task domain. Apply proactively.
 2. **Check for checkpoint** — If `docs/SESSION-CHECKPOINT.md` exists, read it. Resume from last known state instead of re-analyzing.
-3. **Check dead letter queue** — Scan `.github/customizations/AGENT-FAILURES.md` for pending failures related to the current scope.
-4. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
+3. **Check pending approvals** — If the checkpoint has a `## Pending Approvals` section, check for replies using the configured messaging provider's MCP tools (e.g., `conversations_replies` for Slack). Read `.opencastle.json` → `stack.notifications` to determine the provider. If no messaging is configured, skip this step.
+4. **Check dead letter queue** — Scan `.github/customizations/AGENT-FAILURES.md` for pending failures related to the current scope.
+5. **Load domain skills** — Based on the task description, load the appropriate skills before writing code. Don't start coding without the relevant skill loaded.
 
 ### Template for Delegation Prompts
 
@@ -39,19 +40,22 @@ Include this reminder in every delegation:
 
 ```
 **Session Start:** Read `.github/customizations/LESSONS-LEARNED.md` before starting.
-Check `docs/SESSION-CHECKPOINT.md` for prior state. Load relevant skills
-before writing code.
+Check `docs/SESSION-CHECKPOINT.md` for prior state and pending approvals.
+If pending approvals exist, check for replies via the messaging provider.
+Load relevant skills before writing code.
 ```
 
 ---
 
 ## Hook: on-session-end
 
-**When:** Before the agent yields control back to the user or completes its task.
+**When:** Before the agent yields control back to the user — every time, unconditionally.
+
+> **You MUST log every session.** No threshold, no exceptions, no "too small to log."
 
 ### Actions
 
-1. **Log the session** — Append a JSON line to `.github/customizations/logs/sessions.ndjson` with: agent name, task summary, files changed, duration estimate, outcome (success/partial/failed), and lessons count.
+1. **Log the session (MANDATORY)** — Append a JSON line to `.github/customizations/logs/sessions.ndjson` with: agent name, task summary, files changed, duration estimate, outcome (success/partial/failed), and lessons count. See `general.instructions.md` § Observability Logging for full rules.
 2. **Save checkpoint** (Team Lead only) — If work is incomplete, write `docs/SESSION-CHECKPOINT.md` with current state so the next session can resume. Load **session-checkpoints** skill for format.
 3. **Verify lessons captured** — If any retries occurred during the session, confirm that each retry resulted in a lesson entry in `LESSONS-LEARNED.md`.
 4. **Memory merge check** — If `LESSONS-LEARNED.md` has grown significantly (5+ new entries this session), flag for memory merge consideration.
@@ -143,7 +147,9 @@ Each workflow's **Compound phase** naturally serves as the on-session-end hook f
 ## Anti-Patterns
 
 - **Skipping on-session-start** — Leads to repeated mistakes already documented in lessons learned
-- **Forgetting session logging** — Makes performance tracking and agent improvement impossible
+- **Forgetting session logging** — Makes the observability dashboard empty and performance tracking impossible. This is the #1 most common failure.
+- **Treating logging as optional** — Every session gets logged. No threshold, no exceptions.
+- **Batch-logging retrospectively** — Log each task as it completes, not all at once at the end of a long conversation.
 - **Partial post-delegate checks** — "It compiled, ship it" without checking acceptance criteria
 - **No cleanup** — Temp files accumulate and confuse future sessions
 - **Hooks as blockers** — Hooks should add ~2 minutes overhead, not 20. If a hook takes too long, skip the optional parts

package/src/orchestrator/skills/session-checkpoints/SKILL.md

@@ -54,6 +54,18 @@ Phase N of M — Brief description of what this phase does
 |------|--------|-------|-------------|-------|
 | Description | TAS-AA | Agent Name | TAS-ZZ | file4.ts, file5.ts |
 
+## Pending Approvals
+
+Approval requests posted to the messaging provider that haven't been answered yet.
+The `on-session-start` hook checks for replies when a new session begins.
+
+| Provider | Channel | Thread ID | Question | Posted At |
+|----------|---------|-----------|----------|-----------|
+| slack | C0AHAQFJ7C1 | 1772393542.345149 | Run migration on production? | 2026-03-01 14:30 |
+
+If the user answered in the VS Code chat during the previous session, remove
+the row from this table — the approval was already resolved.
+
 ## Key Decisions Made
 
 - Decision 1: Why this approach was chosen

package/src/orchestrator/skills/slack-notifications/SKILL.md

@@ -13,37 +13,90 @@ Agent communication patterns via the Slack MCP server. Enables agents to post pr
 
 | Field | Value |
 |-------|-------|
-| **URL** | `https://mcp.slack.com/mcp` |
-| **Type** | Streamable HTTP (JSON-RPC 2.0) |
-| **Auth** | OAuth 2.0 via registered Slack app (`client_id` + `client_secret`) |
-| **Supported clients** | Claude.ai, Claude Code, Cursor, Perplexity |
+| **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 |
 
-### Required OAuth Scopes
+### Authentication
 
-The Slack app must be granted scopes for the operations agents will perform:
+The `@kazuph/mcp-slack` server supports multiple token types (only one is needed):
+
+| 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:
 
 | Scope | Purpose |
 |-------|---------|
-| `channels:read` | List and search public channels |
-| `channels:history` | Read messages in public channels |
 | `chat:write` | Post messages and replies |
-| `users:read` | Look up user profiles for mentions |
-| `reactions:read` | Read emoji reactions (approval signals) |
-| `reactions:write` | Add emoji reactions (acknowledgments) |
-| `search:read` | Search messages and files |
+| `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.
 
 ## Available MCP Tools
 
-The Slack MCP server exposes tools for:
+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) |
+
+### 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) |
 
-- **Search** — `slack_search_messages`, `slack_search_channels`, `slack_search_users`
-- **Read** — `slack_get_channel_history`, `slack_get_thread_replies`, `slack_get_channel_info`
-- **Write** — `slack_post_message`, `slack_reply_to_thread`, `slack_add_reaction`
-- **Canvases** — `slack_create_canvas`, `slack_update_canvas`
+### Users
 
-Tool names may vary by MCP server version. Use tool discovery to list available tools at runtime.
+| 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.
+
+### Key Differences from Documented 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
 
 ## Agent Notification Patterns
 
@@ -80,46 +133,93 @@ Format:
 
 ## Bi-Directional Communication
 
-### Human-in-the-Loop Approval
+### Dual-Channel Approval Pattern
 
-When an agent needs approval before proceeding (destructive operations, production deployments, large refactors):
+Approval requests are always **dual-channel** — posted to Slack AND asked in the chat window. The first response (from either channel) wins.
 
-1. **Post approval request** to the channel with clear options:
+```
+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)
+```
+
+**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:
    ```
    ⏳ **Approval Required**
    Task: TAS-42 — Database migration adds `price_range` column
    Action: Run migration on production database
-   
-   React with:
-   ✅ — Approve and proceed
-   ❌ — Reject and stop
-   💬 — Reply in thread with questions
+
+   Reply in this thread with:
+   ✅ "approved" — Approve and proceed
+   ❌ "rejected" — Reject and stop
+   💬 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.
    ```
 
-2. **Poll for response** — Read reactions or thread replies to determine the decision
-3. **Acknowledge** — Post confirmation of the action taken
+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:
 
-1. Use `slack_get_thread_replies` to read replies to the approval message
-2. Use `slack_get_channel_history` with a time range to find recent directives
-3. Parse reactions on messages for quick yes/no signals
+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
+
+### Resolution Rule
+
+- **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)
 
 ### Parsing Conventions
 
 | Signal | Meaning |
 |--------|---------|
-| ✅ reaction | Approved — proceed |
-| ❌ reaction | Rejected — stop and report |
-| 👀 reaction | Acknowledged — user is reviewing |
-| Thread reply | Detailed instructions or questions |
+| 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 |
 
+> **Note:** Reactions (emoji responses) are not available via the Slack MCP server. Use thread replies for all approval workflows.
+
 ## Channel & Thread Conventions
 
-### Channel Structure
+### Channel Configuration
+
+Project-specific channel mappings are defined in `.github/customizations/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 |
 |---------|---------|
@@ -170,9 +270,9 @@ Slack uses a markdown-like syntax with some differences:
 
 ## Security Considerations
 
-- **OAuth tokens** are managed by the MCP server — agents never see raw tokens
-- **Scope minimization** — request only the scopes agents actually need
-- **Channel restrictions** — limit the app to specific channels rather than granting workspace-wide access
+- **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)