@@ -5,21 +5,40 @@ A sample Slack agent that showcases [Slack Code](https://docs.slack.dev/ai/slack
 > [!WARNING]
 > **This agent runs commands generated by a language model on the machine running the app.** Only run it against trusted, throwaway repositories, on a machine you're comfortable letting it operate. Refer to the framework README for how command approvals work.
 
-## Choose your framework
+## Choose Your Framework
 
-| App                   | Directory            | Get started                                  | Framework                                                                  |
-| --------------------- | -------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
-| **Claude Agent SDK**  | `claude-agent-sdk/`  | [View README](./claude-agent-sdk/README.md)  | [claude-agent-sdk](https://platform.claude.com/docs/en/agent-sdk/overview) |
-| **OpenAI Agents SDK** | `openai-agents-sdk/` | [View README](./openai-agents-sdk/README.md) | [openai-agents](https://openai.github.io/openai-agents-python/)            |
-| **Pydantic AI**       | `pydantic-ai/`       | [View README](./pydantic-ai/README.md)       | [pydantic-ai](https://pydantic.dev/docs/ai/overview/)                      |
+This repo contains the same app built with three different AI agent frameworks. Pick the one that fits your stack:
 
-## What it can do
+| App | Directory | Get Started | Framework |
+|-----|-----------|-------------|-----------|
+| **Claude Agent SDK** | `claude-agent-sdk/` | [View README](./claude-agent-sdk/README.md) | [claude-agent-sdk](https://platform.claude.com/docs/en/agent-sdk/overview) |
+| **OpenAI Agents SDK** | `openai-agents-sdk/` | [View README](./openai-agents-sdk/README.md) | [openai-agents](https://openai.github.io/openai-agents-python/) |
+| **Pydantic AI** | `pydantic-ai/` | [View README](./pydantic-ai/README.md) | [pydantic-ai](https://pydantic.dev/docs/ai/overview/) |
+
+All implementations share the same Slack listener layer and the same user experience. The only difference is how the agent is defined and executed under the hood.
+
+## What It Can Do
+
+The coding agent interacts with users through four entry points:
 
-- **Channel @mentions and direct messages** — Mention the agent with a task, or message it directly. Quick questions get an answer in place; work that takes more than one message gets a code channel linked back to your message, along with the conversation it came from.
-- **Code channels** — Keep chatting in the channel without an @mention. The agent writes its plan to a Plan tab you can comment on, publishes its changes to the code tab, and pins the repo, branch, and CI status to the context bar.
-- **Command approvals** — File edits, read-only commands, and local git changes run right away. Anything else, like running tests, posts Approve and Deny buttons and waits for your decision.
-- **Slash commands** — The agent registers commands like `/run-tests` for each channel and decides what each one does.
-- **Wrap up** — When you say the work is done, the agent posts a summary back to your original message and archives the channel.
 - **App Home** — The Home tab explains how to start a task.
+- **Direct Messages** — Message the agent directly. Quick questions get an answer in place; work that takes more than one message gets a code channel linked back to your message.
+- **Channel @mentions** — Mention the agent in any channel with a task and a repo. It answers in place, or creates a code channel for the work along with the conversation it came from.
+- **Code Channels** — Keep chatting in the channel without an @mention. The agent writes its plan to a Plan tab you can comment on, publishes its changes to the code tab, and pins the repo, branch, and CI status to the context bar.
+
+In a code channel, file edits, read-only commands, and local git changes run right away. Anything else, like running tests, posts Approve and Deny buttons and waits for your decision. The agent also registers slash commands like `/run-tests` for each channel and decides what each one does. When you say the work is done, it posts a summary back to your original message and archives the channel.
+
+## Using the App
+
+Once the agent is running, there are several ways to interact:
+
+- **App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
+- **Direct Messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
+- **Channel @mentions** — Invite the agent to a channel by typing `/invite @agent-name`, then @mention it with a task and a repo. It answers in the thread, or replies with a link to a new code channel for the work.
+- **Code Channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
 
 For full setup instructions, pick a framework above and follow the README in that directory.
+
+## Local Development
+
+This repo uses [`slack-bolt`](https://pypi.org/project/slack-bolt/) from PyPI.
@@ -262,15 +262,15 @@ python3 app_oauth.py
 
 ### Using the App
 
-Once the agent is running, invite it to a channel by typing `/invite @agent-name` in the message box.
+Once the agent is running, there are several ways to interact:
 
-**Channel @mentions** — @mention the agent in a thread with a question about the conversation, like _what did we decide here?_, and it answers in the thread. @mention it with a task and a repo, like _add a "hello world" to the README of `<repo>`_, and it replies with a link to a new code channel for the work.
+**App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
 
-**Direct messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
+**Direct Messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
 
-**Code channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
+**Channel @mentions** — Invite the agent to a channel by typing `/invite @agent-name` in the message box, then @mention it in a thread with a question about the conversation, like _what did we decide here?_, and it answers in the thread. @mention it with a task and a repo, like _add a "hello world" to the README of `<repo>`_, and it replies with a link to a new code channel for the work.
 
-**App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
+**Code Channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
 
 ### Linting
 
@@ -285,7 +285,8 @@ ruff format
 ### Testing
 
 ```sh
-pytest
+# Run pytest from root directory for unit testing
+pytest .
 ```
 
 ## Project Structure
@@ -336,7 +337,7 @@ The `outcome.py` file defines the `RunOutcome` that `agent.py` returns and `turn
 
 The `context.py` file reads the thread or direct message a request came from, so the agent can follow the conversation.
 
-The `guardrails.py` file holds the SDK hooks that gate tool calls: the approval check for `run_command`, which defers a command that needs approval, and the check that skips every tool call once the session is stopped.
+The `guardrails.py` file holds the SDK hooks around tool calls: the approval check for `run_command`, which defers a command that needs approval, and the check that skips every tool call once the session is stopped.
 
 The `sessions.py` file keeps each code channel's session in memory: its working directory, plan canvas, conversation history, and messages waiting for the next turn. It also defines the `AgentDeps` and `RequestDeps` dataclasses passed to the agents at runtime, providing access to the Slack client and the session or request.
 
 
@@ -260,15 +260,15 @@ python3 app_oauth.py
 
 ### Using the App
 
-Once the agent is running, invite it to a channel by typing `/invite @agent-name` in the message box.
+Once the agent is running, there are several ways to interact:
 
-**Channel @mentions** — @mention the agent in a thread with a question about the conversation, like _what did we decide here?_, and it answers in the thread. @mention it with a task and a repo, like _add a "hello world" to the README of `<repo>`_, and it replies with a link to a new code channel for the work.
+**App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
 
-**Direct messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
+**Direct Messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
 
-**Code channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
+**Channel @mentions** — Invite the agent to a channel by typing `/invite @agent-name` in the message box, then @mention it in a thread with a question about the conversation, like _what did we decide here?_, and it answers in the thread. @mention it with a task and a repo, like _add a "hello world" to the README of `<repo>`_, and it replies with a link to a new code channel for the work.
 
-**App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
+**Code Channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
 
 ### Linting
 
@@ -283,7 +283,8 @@ ruff format
 ### Testing
 
 ```sh
-pytest
+# Run pytest from root directory for unit testing
+pytest .
 ```
 
 ## Project Structure
@@ -324,7 +325,7 @@ Every incoming request is routed to a "listener". This directory groups each lis
 
 ### `/agent`
 
-The `agent.py` file defines the routing agent and the coding agent with their tools, and starts and resumes their runs. It's the only file outside `tools` that uses the OpenAI Agents SDK.
+The `agent.py` file defines the routing agent and the coding agent with their tools, and starts and resumes their runs. Along with `guardrails.py` and `tools`, it's the only code that uses the OpenAI Agents SDK.
 
 The `prompts.py` file holds both agents' prompts.
 
@@ -334,7 +335,7 @@ The `outcome.py` file defines the `RunOutcome` that `agent.py` returns and `turn
 
 The `context.py` file reads the thread or direct message a request came from, so the agent can follow the conversation.
 
-The `guardrails.py` file holds the SDK hooks that gate tool calls: the approval check for `run_command`, and the guardrail that skips every tool call once the session is stopped.
+The `guardrails.py` file holds the SDK hooks around tool calls: the approval check for `run_command`, and the guardrail that skips every tool call once the session is stopped.
 
 The `sessions.py` file keeps each code channel's session in memory: its working directory, plan canvas, conversation history, and messages waiting for the next turn. It also defines the `AgentDeps` and `RequestDeps` dataclasses passed to the agents at runtime, providing access to the Slack client and the session or request.
 
 
@@ -143,7 +143,7 @@ pip install -e ".[dev]"
 
 ## Providers
 
-This app supports both Anthropic and OpenAI as AI providers. Set at least one API key. If both are set, Anthropic is used by default.
+This app supports both Anthropic and OpenAI as AI providers. Set at least one API key — if both are set, Anthropic is used by default.
 
 ### Anthropic Setup
 
@@ -272,15 +272,15 @@ python3 app_oauth.py
 
 ### Using the App
 
-Once the agent is running, invite it to a channel by typing `/invite @agent-name` in the message box.
+Once the agent is running, there are several ways to interact:
 
-**Channel @mentions** — @mention the agent in a thread with a question about the conversation, like _what did we decide here?_, and it answers in the thread. @mention it with a task and a repo, like _add a "hello world" to the README of `<repo>`_, and it replies with a link to a new code channel for the work.
+**App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
 
-**Direct messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
+**Direct Messages** — Open the agent's _Messages_ tab and ask a question or describe a task, or pick a suggested prompt. It answers there, or links a code channel for bigger work.
 
-**Code channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
+**Channel @mentions** — Invite the agent to a channel by typing `/invite @agent-name` in the message box, then @mention it in a thread with a question about the conversation, like _what did we decide here?_, and it answers in the thread. @mention it with a task and a repo, like _add a "hello world" to the README of `<repo>`_, and it replies with a link to a new code channel for the work.
 
-**App Home** — Open the agent in Slack and click the _Home_ tab to see how to start a task.
+**Code Channels** — Follow the work in the new channel. Approve or deny commands as they come up, comment on the Plan tab, review the diff in the code tab, and send follow-ups without an @mention. Say you're done to wrap up and archive the channel.
 
 ### Linting
 
@@ -295,7 +295,8 @@ ruff format
 ### Testing
 
 ```sh
-pytest
+# Run pytest from root directory for unit testing
+pytest .
 ```
 
 ## Project Structure
@@ -336,7 +337,7 @@ Every incoming request is routed to a "listener". This directory groups each lis
 
 ### `/agent`
 
-The `agent.py` file defines the routing agent and the coding agent with their tools, picks their models, and starts and resumes their runs. It and `guardrails.py` are the only files outside `tools` that use Pydantic AI.
+The `agent.py` file defines the routing agent and the coding agent with their tools, picks their models, and starts and resumes their runs. Along with `guardrails.py` and `tools`, it's the only code that uses Pydantic AI.
 
 The `prompts.py` file holds both agents' prompts.