SLACK API // WORKSPACE CREDENTIALS

Generate configuration tokens.

These workspace-level tokens let Agent Barn prepare a new Slack app. Generate both values and keep them ready for the next steps.

01.1
Open Slack API → Your Apps.
Go to api.slack.com/apps ↗, sign in, and confirm that you are working in the workspace where this agent should operate.
01.2
Find “Your App Configuration Tokens.”
Scroll near the bottom of the page and click Generate Token.
Slack API → Your Apps → App Configuration Tokens.
01.3
Select the workspace and generate the pair.
Choose the same workspace, then click Generate. Slack returns a configuration access token and an xoxe- refresh token.
1 // Select the workspace. 2 // Generate the token pair.
01.4
Store both values securely.
The access token authorizes app creation and expires after 12 hours. The refresh token rotates that access. Never place either value in chat, logs, prompts, or URLs.
01.5
Submit the token pair in Agent Barn.
Paste the configuration access token and xoxe- refresh token into their matching fields, then continue while the access token is still valid.

SLACK APP // PUBLIC IDENTITY

Define the bot identity.

Use recognizable, role-oriented metadata. These values are visible to teammates and can be changed later.

02.1
Choose the display name.
This name appears in Slack messages, mentions, and the app directory. Avoid secrets, environment names, or workspace-specific data.
RECOMMENDEDAgentBarn_Recipe_Documentation
02.2
Write a one-sentence description.
Describe the outcome teammates can expect rather than the implementation behind it.
SUGGESTED
Turns merged pull requests and linked Jira work into Confluence updates, changelog entries, and a weekly digest.
02.3
Choose the icon background color.
Pick a readable color that follows your workspace convention. Agent Barn orange is the recommended default.
Aubergine#511152
A familiar Slack-adjacent choice.
Blue#1264A3
Calm and conventional for utility bots.
Green#2EB67D
Useful for workflow or status-oriented agents.
Amber#ECB22E
High visibility for reminders and alerts.
Agent Barn orange#CC4400
Recommended for a consistent Agent Barn identity.
02.4
Review the public metadata.
Confirm that the name states the role, the description states the result, the color remains legible at small sizes, and no sensitive information is exposed.
02.5
Create the app and confirm it appears in Slack.
Save the identity in Agent Barn, complete app creation, then confirm the new app appears under Your Apps in the intended workspace before continuing.

SLACK API // SOCKET MODE

Connect the new Slack app.

Create the app-level token, install the bot, and store the two resulting credentials that Agent Barn needs.

Open Slack apps ↗

03.1
Select the new app and verify its connection settings.
Return to Your Apps ↗, open the app created for this recipe, verify the workspace, and confirm Socket Mode and the recipe's event subscriptions are enabled.
03.2
Open App-Level Tokens and start a new token.
In Basic Information → App-Level Tokens, click Generate Token and Scopes. The crop keeps the only control you need in view.
Basic Information → App-Level Tokens → Generate Token and Scopes.
03.3
Name the Socket Mode token and add connections:write.
Use a descriptive name such as agent-barn-socket. Add only connections:write, which lets Slack route Socket Mode events over WebSockets, then click Generate.
1 // Name the token. 2 // Confirm connections:write. 3 // Generate it.
03.4
Copy the app-level token.
Slack displays the xapp- token after generation. Click Copy, then keep it ready for the Agent Barn App-level token field. The token is blurred in this reference.
The generated token has connections:write.
03.5
Install the app to the workspace.
Open Install App, then choose Install to [your workspace]. Review the requested permissions, make sure the workspace selector is correct, and choose Allow.
Install App → Install to your workspace.
1 // Confirm the workspace. 2 // Approve only after reviewing permissions.
03.6
Find the Bot User OAuth Token after installation.
After installation, Slack shows an OAuth Tokens section containing the Bot User OAuth Token. Click Copy and keep the xoxb- value ready for Agent Barn. The token is blurred in this reference.
Installed App Settings → OAuth Tokens → Bot User OAuth Token → Copy.
03.7
Enter both tokens in Agent Barn.
Paste the xapp- value into App-level token and the xoxb- value into Bot token.
03.8
Save and verify the connected app.
Save both fields and confirm Agent Barn resolves the expected Slack app and workspace. Stop if either identity is wrong.

Keep them private

Enter Slack tokens only in their matching Agent Barn fields. Do not include them in messages or screenshots.

AGENT BARN // OPERATING BOUNDARIES

Configure how the teammate operates.

Work through these settings in order. Each controls a different part of the agent’s behavior or access.

04.1
IDENTITY
Name the teammate for its role.
The operational name appears in dashboards and audit history. A short human name makes conversations and mentions easier.
OPERATIONAL NAME
AgentBarn_Recipe
Clear in dashboards and logs.
SUGGESTED HUMAN NAME
Aria
Easy to mention and remember.
04.2
MODEL
Choose the model that performs the work.
The model affects capability, speed, and cost. The supplied configuration shows DeepSeek: DeepSeek V4 Flash 0731. Confirm it is available and appropriate for this recipe’s complexity and data sensitivity.
How to decide
Use a fast model for structured, repeatable work. Use a more capable model for ambiguous context or nuanced reasoning. Evaluate representative tasks before granting broader access.
04.3
COMMAND APPROVAL
Decide when a human must approve commands.
Start with the most restrictive mode that still makes the workflow useful.
Current default shown: Auto.
RECOMMENDED START
Auto
Low-risk commands run automatically; higher-risk commands still require approval.
MAXIMUM OVERSIGHT
Manual
The agent asks before every command. Best for pilots and sensitive systems.
NO APPROVAL GATE
Off
All prompts are skipped. Use only with tightly sandboxed, narrowly scoped, reversible tools.
04.4
CHANNEL ACCESS
Choose which channels the agent may answer in.
Slack controls which channels the app can see; this policy controls where the agent may respond.
Current default shown: Allowlist.
RECOMMENDED START
Allowlist
Respond only in approved channels. Best for pilots and team-specific workflows.
BROAD AVAILABILITY
Open
Respond in any reachable channel. Use only for intentionally workspace-wide roles.
04.5
DIRECT MESSAGES
Control who can start private conversations.
Direct messages remove shared-channel context and oversight. Enable them only when private interaction is genuinely needed.
Current default shown: Off.
RECOMMENDED START
Off
Ignore direct messages and keep work visible in approved channels.
LIMITED PRIVATE ACCESS
Allowlist
Only designated operators and reviewers may send direct messages.
WORKSPACE-WIDE DMS
Open
Anyone who can reach the app may DM it. Use only with strong identity and tool controls.
04.6
VERBOSITY
Choose how much work the agent narrates.
This changes what teammates see while the agent works; it does not change capabilities or approvals.
Current default shown: Concise.
VISIBLE EXECUTION
Verbose
Announces each step. Useful during onboarding, debugging, and supervised pilots.
RECOMMENDED STEADY STATE
Concise
Provides final answers without narrating every intermediate step.
04.7
Add the intended Slack destinations.
Invite the app to each permitted channel. When Allowlist is selected, add the same channels and approved direct-message users in Agent Barn before testing.
04.8
Configure the recipe trigger and workflow.

Trigger: A pull request is merged or a scheduled digest is due.
1. Detect change. Read the merged pull request and linked Jira context.
2. Draft update. Prepare a Confluence update or changelog entry.
3. Check scope. Keep the update within configured sources and policies.
4. Share digest. Post the prepared summary to the allowed Slack channel.
04.9

Apply the recipe requirements and review rule.

Template
Documentation agent instructions and output format.
Skills
GitHub or Bitbucket plus Jira and Confluence access.
Channels
A permitted Slack channel for digests and questions.

Review rule
Review generated documentation before treating it as the final record of a product or engineering decision.

Suggested starting profile

Auto command approval · Channel allowlist · Direct messages off · Concise responses. Expand access only after representative tests and review of the agent’s tools and data boundaries.

AGENT BARN // TOOLS AND CREDENTIALS

Assign the skills this recipe needs.

Skills connect the agent to external platforms. Select only the integrations required for the workflow, then connect each one with a dedicated or approved shared credential.

CHOOSE ONE PROVIDER

GitHub or Bitbucket

source control

Read merged pull requests, diffs, labels, and linked engineering context.

Credential: A GitHub App or Bitbucket access token scoped to the repositories this recipe documents.
Permissions: Repository metadata: read · Pull requests and diffs: read · Comments: write only if the workflow posts review notes

Choose the provider that owns the source repositories.
Limit installation or token access to the repositories in scope.
Subscribe only to merged pull-request events and any explicitly required update events.

REQUIRED

Jira and Confluence

atlassian

Read linked Jira work and create or update documentation and changelog content in approved Confluence spaces.

Credential: One Atlassian account email and site URL, with an API credential verified for the required Jira and Confluence operations.
Permissions: Jira projects and linked issues: read · Confluence target spaces: view · Confluence pages: add or update where required · Comments: add only if the recipe uses review comments

Identify the Jira projects referenced by the source repositories.
Identify the destination Confluence spaces and page hierarchy.
Use an account whose Jira and Confluence access is limited to those locations.
Validate Jira reads and Confluence writes in non-production test locations.

05.1
Keep required skills; resolve “choose one” integrations.
Skills marked Required by template are part of this recipe’s workflow. When a card names alternatives, choose the provider your team actually uses. Optional skills should remain disconnected until a defined task needs them.
05.2
Choose how each credential will be supplied.
Choose Enter credentials to connect an account now. Choose Use shared credential when the correct workspace account is already connected.
NEW CONNECTION
Enter credentials
Connect the account required by this recipe.
EXISTING CONNECTION
Use shared credential
Select a matching account already available in Agent Barn.
05.A1
Record the Atlassian site URL.
This recipe connects to Jira and Confluence. Copy only the site origin, for example https://aai-labs.atlassian.net. Omit Confluence space and Jira project paths.
Use the site origin only; omit everything after .net.
05.A2
Confirm Jira and Confluence access.
The API token inherits its Atlassian account’s product and content permissions. For Documentation Agent, the required boundary is: Jira projects and linked issues: read · Confluence target spaces: view · Confluence pages: add or update where required · Comments: add only if the recipe uses review comments.
One credential, verified twice
When Jira and Confluence are both required, test the same credential against one permitted Jira item and one permitted Confluence page. Confirm locations outside the configured boundary remain unavailable.
05.A3
Open Atlassian account security.
Open the profile menu, choose Account settings, then open Security.
1 // Profile menu → Account settings.
2 // Open the Security tab.
05.A4
Open the API token manager.
Choose Create and manage API tokens, then select a standard or scoped token. The choice must match the Authentication Type selected in Agent Barn.
Security → API tokens → Create and manage API tokens.
Choose the token type deliberately.
SHARED JIRA + CONFLUENCE
Non-scoped token
Can use the account’s Jira and Confluence permissions. Limit the account itself and verify both products before reuse.
APP-SPECIFIC ACCESS
Scoped token
Limits API scopes. Create or reuse only a token whose selected app and scopes match the credential block.
05.A5
Name, expire, and copy the token.
Name it AgentBarn_Recipe or another value that identifies the recipe. Choose an expiration date, create the token, and copy the value before closing the dialog.
Choose a recognizable name and expiration.
Copy the token for Agent Barn.
05.A6
Complete the Atlassian credential block.
Enter the site origin, matching authentication type, account email, and API token. Jira and Confluence may use the same saved credential when the token mode and account permissions cover both products.
SITE URL
Shared Atlassian site origin.
AUTHENTICATION TYPE
Scoped or non-scoped.
EMAIL
Account that created the token.
API TOKEN
Token used for Jira and Confluence.
05.S1
Choose GitHub or Bitbucket.
Read merged pull requests, diffs, labels, and linked engineering context. Connect only the provider that owns the repositories for this recipe.
05.G1
GitHub // Enter a dedicated credential.
Choose GitHub → Enter credentials. Use a token created for this recipe instead of a personal token already used by other tools.
05.G2
GitHub // Open the Classic PAT page.
Open Settings → Credentials → Personal access tokens → Tokens (classic). Select Generate new token → Generate new token (classic), or open github.com/settings/tokens ↗.
05.G3
GitHub // Name and expire the token.
Use a note such as AgentBarn_Recipe, choose an expiration date, and continue.
05.G4
GitHub // Select the Classic PAT scopes.
REPO
Repository access, including available private repositories.
READ:ORG
Read organization and team membership.
READ:USER
Read user profile data.
Repository access
The repo scope is broad. Add the specific repository names this recipe should use.
05.G5
GitHub // Generate and copy the token.
Click Generate token and copy the value for the Personal access token field in Agent Barn.
The token value is blurred in this guide.
05.G6
GitHub // Complete the credential fields.
Read the repository header as owner/repository. In this example, aai-labs is Owner / Org and agent-barn is the repository.
Owner / Org: aai-labs · Repository: agent-barn
PERSONAL ACCESS TOKEN
Paste the copied Classic PAT.
OWNER / ORG
Value before the slash.
REPOSITORIES
Add each permitted name after the slash.
EMPTY REPOSITORY LIST
Avoid it; the token could address any repository it can reach.
05.B1
Bitbucket // Record the workspace ID.
Open the target workspace. In a URL such as bitbucket.org/agentbarn/workspace/overview, agentbarn is the workspace ID. You can also confirm it in workspace settings under Workspace ID.
05.B2
Bitbucket // Open Atlassian account security.
Select the Bitbucket profile avatar, choose Account settings, open Security, then choose Create and manage API tokens.
Bitbucket account settings opens the shared Atlassian token manager.
05.B3
Bitbucket // Create a scoped API token.
Select Create API token with scopes, enter a recipe-specific name and expiration, select Bitbucket as the app, and continue to permissions.
05.B4
Bitbucket // Select the required scopes.
READ:USER:BITBUCKET
Read the authenticated account.
READ:WORKSPACE:BITBUCKET
Read the configured workspace.
READ:REPOSITORY:BITBUCKET
Read repository source and metadata.
READ:PULLREQUEST:BITBUCKET
Read pull requests and their context.
05.B5
Bitbucket // Create and copy the token.
Review the selected Bitbucket app and scopes, create the token, and copy it for the API token field in Agent Barn.
05.B6
Bitbucket // Complete the credential fields.
WORKSPACE
Bitbucket workspace ID, such as agentbarn.
REPOSITORIES
Add every permitted repository; avoid an empty list.
EMAIL
Atlassian account email that created the token.
API TOKEN
Paste the Bitbucket-scoped token.
If the Agent Barn panel still says “App password scopes,” use the API-token equivalents above. Bitbucket app passwords are no longer the current credential path.
05.S2
Validate the selected provider boundary.
Test one permitted repository and one repository outside the configured list. Confirm the agent can perform only the operations required by Documentation Agent: Repository metadata: read · Pull requests and diffs: read · Comments: write only if the workflow posts review notes.
05.Z
Validate every selected skill before hiring.
Run one expected action and confirm the recipe cannot reach anything outside its selected accounts and resources. Resolve permission issues before choosing Hire.

FINAL CHECK

Verify the setup before launch.

Run this short review once Slack, Agent Barn, and the required skills are configured.

Confirm the app is installed in the intended Slack workspace.
Verify the xapp- and xoxb- values connect the intended Slack app.
Validate every required skill and confirm its credential has only the intended site, space, project, or repository access.
Test one representative request in an allowlisted channel.
Confirm higher-risk commands still trigger the expected approval path.
Review the agent’s response quality, visibility, and logs before expanding access.
Run the configured trigger: A pull request is merged or a scheduled digest is due.
Confirm the result follows Detect change → Draft update → Check scope → Share digest.
Apply the review rule: Review generated documentation before treating it as the final record of a product or engineering decision.

RECIPE PATH COMPLETE

Documentation Agent is ready for a controlled pilot.

Start with a narrow audience and reversible work, then widen access after observing representative tasks.

Return to recipes →

Set up Documentation Agent in Slack.

Open Slack API → Your Apps.

Find “Your App Configuration Tokens.”

Select the workspace and generate the pair.

Store both values securely.

Submit the token pair in Agent Barn.

Choose the display name.

Write a one-sentence description.

Choose the icon background color.

Review the public metadata.

Create the app and confirm it appears in Slack.

Select the new app and verify its connection settings.

Open App-Level Tokens and start a new token.

Name the Socket Mode token and add connections:write.

Copy the app-level token.

Install the app to the workspace.

Find the Bot User OAuth Token after installation.

Enter both tokens in Agent Barn.

Save and verify the connected app.

Name the teammate for its role.

AgentBarn_Recipe

Aria

Choose the model that performs the work.

Decide when a human must approve commands.

Auto

Manual

Off

Choose which channels the agent may answer in.

Allowlist

Open

Control who can start private conversations.

Off

Allowlist

Open

Choose how much work the agent narrates.

Verbose

Concise

Add the intended Slack destinations.

Configure the recipe trigger and workflow.

Apply the recipe requirements and review rule.

Keep required skills; resolve “choose one” integrations.

Choose how each credential will be supplied.

Enter credentials

Use shared credential

Record the Atlassian site URL.

Confirm Jira and Confluence access.

Open Atlassian account security.

Open the API token manager.

Non-scoped token

Scoped token

Name, expire, and copy the token.

Complete the Atlassian credential block.

Choose GitHub or Bitbucket.

GitHub // Enter a dedicated credential.

GitHub // Open the Classic PAT page.

GitHub // Name and expire the token.

GitHub // Select the Classic PAT scopes.

GitHub // Generate and copy the token.

GitHub // Complete the credential fields.

Bitbucket // Record the workspace ID.

Bitbucket // Open Atlassian account security.

Bitbucket // Create a scoped API token.

Bitbucket // Select the required scopes.

Bitbucket // Create and copy the token.

Bitbucket // Complete the credential fields.

Validate the selected provider boundary.

Validate every selected skill before hiring.

Documentation Agent is ready for a controlled pilot.

Name the Socket Mode token and add `connections:write`.