docs: add Slack+GitHub+Linear daily organization automation

[neubig]

Summary

• Add a recommended prompt-preset automation for Slack+GitHub+Linear daily organization.
• Keep the prompt anonymized with placeholders for user, scope, recipient, and timezone.
• Link the new recommended automation from the README.

Validation

• Ran git diff --check.
• Ran a simple anonymization grep for personal names, channel names, and org-specific examples in the new prompt.

This PR was created by an AI agent (OpenHands) on behalf of the user.

@neubig can click here to continue refining the PR

Related issue: #135

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	1	0	100%
app.py	151	83	45%	41, 44, 47, 53, 55, 58, 61–64, 67, 72–74, 76, 81–82, 84, 86–88, 90, 94, 96–97, 99–100, 103–109, 112–113, 116, 123–124, 127–128, 132, 140–141, 144, 151–152, 154, 157–158, 161, 166–174, 176–178, 284–286, 291–292, 294–295, 297, 300–302, 304–305, 307–308, 313–314, 318, 321, 323
auth.py	160	7	95%	88, 116, 125, 162, 335, 343–344
config.py	158	0	100%
constants.py	17	0	100%
db.py	67	29	56%	60, 74–75, 78–80, 82, 89, 92–93, 96, 104, 111, 144, 147–148, 152–153, 161, 169, 174, 201, 204–210
dispatcher.py	186	45	75%	70, 82, 84–85, 137, 199–202, 237, 240, 255–256, 262–264, 281–282, 288–292, 295–297, 307, 373–374, 399–406, 426, 441–442, 456–457, 466–467, 469
event_router.py	59	19	67%	83, 88, 119–121, 137–138, 156, 158, 160–161, 163, 173, 179–181, 184, 186, 188
exceptions.py	4	0	100%
execution.py	220	133	39%	39–41, 76–79, 87–91, 93, 101–103, 108–112, 114, 128–131, 133, 135, 137–140, 142–147, 149, 151–158, 160–161, 163, 199–201, 207–209, 220–223, 229–231, 271–275, 284, 292, 296, 298–299, 304–305, 310, 388–389, 473–475, 477–483, 486–487, 489, 491–493, 496, 499, 502–505, 507, 510–511, 514–516, 520–521, 525–528, 530, 538–539, 543–545, 547–553, 557, 559, 568–570, 572–574
filter_eval.py	50	2	96%	161–162
logger.py	55	17	69%	37, 50–51, 53–59, 74, 77, 101, 103–106
models.py	81	0	100%
preset_router.py	190	56	70%	143–145, 255–256, 261–268, 273, 276, 278–279, 291–294, 296–300, 305, 314, 386–388, 501–502, 507–514, 519, 522, 524–525, 537–540, 542–546, 551, 561
router.py	142	77	45%	92–93, 113, 115, 118, 120, 134, 147, 149–150, 152–153, 155–156, 159–161, 172–174, 194–196, 202–204, 208–209, 228–229, 231, 234, 259–262, 281, 284, 287, 294, 296, 330–332, 335–337, 341–342, 347, 351–354, 356, 364, 366–367, 372–373, 376, 378, 380–382, 385–388, 393, 395–396, 405, 426–428, 432
scheduler.py	61	9	85%	137–138, 175–176, 191–192, 202–203, 205
schemas.py	270	17	93%	32, 166, 172–174, 233–235, 237, 342–343, 346, 351, 356, 500, 508, 515
trigger_matcher.py	28	3	89%	72–74
uploads.py	107	59	44%	142–145, 153–155, 161–162, 165, 174–175, 178–179, 187–188, 190–193, 196–199, 201, 203–205, 207–210, 212–213, 215, 230, 236–237, 240, 243, 246, 249, 251, 264–265, 279, 282–284, 286–287, 289, 295–296, 309, 317–319, 323
watchdog.py	98	45	54%	55–57, 69–70, 162–163, 204–205, 207, 209, 218, 220–222, 224, 231–233, 235–237, 239–240, 242, 257, 259, 264–267, 269–274, 276–282, 284
webhook_router.py	80	48	40%	57, 82–83, 107–108, 110, 113–114, 116, 126, 128–132, 137, 139, 151, 154, 157, 164–165, 167, 180, 182–183, 188, 204, 206–207, 213–215, 217–218, 220, 235, 237–238, 243–244, 261, 263–264, 270–271, 273, 275
backends
__init__.py	13	0	100%
base.py	29	0	100%
cloud.py	130	62	52%	43–45, 50–52, 103, 116–118, 131–135, 142–143, 145, 147, 159–160, 229–230, 232–233, 235–238, 240–245, 247–255, 257–258, 260, 267–269, 272–273, 275, 282–284, 289–293, 295
local.py	43	0	100%
event_schemas
__init__.py	33	1	96%	53
bitbucket_data_center.py	16	0	100%
custom.py	33	5	84%	52–53, 64–66
detection.py	32	0	100%
github.py	125	4	96%	306, 311, 456, 483
jira_dc.py	16	0	100%
presets
__init__.py	0	0	100%
storage
__init__.py	6	0	100%
factory.py	15	1	93%	36
file_store.py	22	5	77%	21, 30, 35, 40, 64
google_cloud.py	72	11	84%	49, 97–102, 136–137, 190, 192
local.py	68	0	100%
s3.py	112	15	86%	56, 100, 102–103, 107, 109, 190, 213–215, 269–270, 275, 337–338
utils
__init__.py	5	0	100%
agent_server.py	53	0	100%
api_key.py	32	24	25%	40–41, 46–48, 50, 55, 60, 62–65, 67–68, 70–71, 73, 79, 81–82, 89, 91–92, 98
cron.py	45	6	86%	39, 45, 74, 80, 123, 140
log_context.py	10	0	100%
model_profiles.py	11	0	100%
run.py	84	14	83%	74–76, 183–184, 200–202, 207–209, 256, 262–263
sandbox.py	71	61	14%	49–50, 55–58, 60–62, 64–70, 80–81, 86–92, 115–116, 118–122, 124–128, 159–160, 162, 164–167, 172–173, 176, 180–181, 187–189, 194–196, 201–202, 210–212, 214
tarball_validation.py	48	0	100%
time.py	10	0	100%
webhook.py	57	9	84%	49, 54, 122, 132–134, 140, 203–204
TOTAL	3376	867	74%

[github-actions]

🚀 Deploy Preview PR Created/Updated

A deploy preview has been created/updated for this PR.

Deploy PR: https://github.com/OpenHands/deploy/pull/4377
Automation SHA: 914e8e87901ba2342597253b98d3206e823dd1a2
Last updated: May 28, 2026, 01:15:37 AM ET

Once the deploy PR's CI passes, the automation service will be deployed to the feature environment.

[all-hands-bot]

🟢 Good taste - Clean, comprehensive documentation for a useful automation pattern.

This PR establishes the first recommended automation example with:

• Proper placeholder usage for sensitive values
• Comprehensive safety rules (access verification, graceful degradation)
• Conservative approach to avoid duplicates and weak matches
• Clear structure with well-defined tasks
• Appropriate timeout (30 min) for the complex workflow

The automation template is well-suited for the prompt preset since it requires judgment for issue matching, priority selection, and summarization.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW
  Documentation-only change adding a template/example file. No code changes, no runtime behavior affected.

VERDICT:
✅ Worth merging: Well-structured documentation that follows best practices.

KEY INSIGHT:
This template demonstrates the right balance between comprehensiveness and usability - detailed enough to be actionable while using placeholders to keep it reusable.

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/automation/actions/runs/26409964296

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

🟢 Good taste - Clean, well-structured documentation for a practical automation pattern.

This PR adds comprehensive documentation for a Slack+GitHub+Linear daily organization automation with:

• Proper placeholder usage to prevent accidental credential exposure
• Clear safety rules (access verification, graceful degradation, conservative matching)
• Well-defined tasks with appropriate level of detail
• Reasonable 30-minute timeout for the complex workflow

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

Pure documentation addition with no code changes, no breaking changes, and no security concerns. The prompt includes good safety guidance and uses placeholders correctly.

VERDICT:
✅ Worth merging: Clean documentation that provides value to users

KEY INSIGHT:
This template demonstrates proper automation design with conservative safeguards and clear user guidance through placeholders.

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/automation/actions/runs/26490763497

[all-hands-bot]

🟡 Acceptable — Well-structured, thoughtful prompt template with solid safety rules. A few usability gaps worth addressing before users run into them.

---

[IMPROVEMENT OPPORTUNITIES]

Missing Linear team/project placeholder (impacts usability)

Task 2 step 3 instructs the agent to "create one in the appropriate Linear team/project," but the Identity and scope section (and the placeholder list in the intro) provides no [LINEAR_TEAM_QUERY] or [LINEAR_PROJECT_QUERY] placeholder. In practice, a workspace with multiple teams (e.g. Backend, Platform, Infra) will cause the agent to guess, which can silently route issues to the wrong team. Adding a placeholder and a corresponding identity line (e.g., - Linear team: resolve by searching for [LINEAR_TEAM_QUERY].) closes this gap cleanly.

Missing prerequisites / required secrets section

The document is self-contained enough to copy-and-paste, but nowhere does it tell users which secrets to configure before the automation can run. A user who sets this up for the first time will hit an auth failure in Task 1's access check without knowing which credential is missing. Recommend adding a short "## Required secrets" or "## Prerequisites" section listing the expected secret names (e.g. GITHUB_TOKEN, LINEAR_API_KEY, SLACK_BOT_TOKEN) and pointing to where to register them in OpenHands.

Implicit Linear assignment / In Progress mutation (undisclosed side effect)

Task 2 step 4 silently assigns the configured Linear assignee and moves issues to In Progress whenever an open PR is associated with them. If [GITHUB_ORG_OR_REPO_SCOPE] spans an entire organization this can touch many issues the user didn't personally open, reassigning them from their current owner. This is a real workflow risk that isn't called out anywhere in the "When to use this" section or the safety rules. Worth at minimum adding a bullet: "Changes Linear issue assignee and status for issues with active PRs — review scope before enabling on org-wide repositories."

Curl example prompt field is placeholder text

The example curl command (line 103) shows "prompt": "Paste the anonymized prompt above after replacing bracketed placeholders." — that string is itself meta-text, not a real value. A first-time user who copy-pastes the command will submit a literal instruction to paste text, not the actual prompt. Options: inline a shortened version of the prompt (with ... ellipsis and a note), or add a comment above the block explaining the user must replace that string with the full prompt text from the section above, properly JSON-escaped or heredoc-embedded.

---

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW
  Documentation-only change. No runtime code is modified. The template itself contains automation instructions that touch real external services (GitHub, Linear, Slack), but those only execute when a user deliberately creates the automation with their own credentials and scope.

VERDICT:
✅ Worth merging — the core structure is sound and the safety rules are genuinely good. The gaps above are quality-of-life improvements for first-time users; they don't block a knowledgeable user from using the template correctly.

KEY INSIGHT:
A missing [LINEAR_TEAM_QUERY] placeholder is the only change that could silently misbehave at runtime — everything else is documentation quality.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing.
2. Re-request a review — the reviewer reads guidelines from the PR branch, so your changes take effect immediately.

Was this review helpful? React with 👍 or 👎 to give feedback.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

The placeholder list includes [GITHUB_USERNAME], [LINEAR_ASSIGNEE_QUERY], [GITHUB_ORG_OR_REPO_SCOPE], [SLACK_RECIPIENT_QUERY], and [IANA_TIMEZONE], but there is no [LINEAR_TEAM_QUERY] (or [LINEAR_PROJECT_QUERY]). Task 2 step 3 will tell the agent to pick "the appropriate Linear team/project" with no guidance, which means it will guess. In multi-team workspaces that silently routes new issues to the wrong team. Suggest adding a placeholder here and a corresponding Identity and scope line such as:

- Linear team: resolve by searching for [LINEAR_TEAM_QUERY]. Do not guess if multiple teams exist.

[all-hands-bot]

"The appropriate Linear team/project" is undefined at this point. The Identity and scope block above (line ~47) specifies assignee and assignee query, but not team. Without a [LINEAR_TEAM_QUERY] placeholder in scope the agent has to infer the team, which is unreliable in workspaces with multiple teams. This line should reference the placeholder once it is added.

[all-hands-bot]

This step silently changes assignee and status on Linear issues the user may not own. If [GITHUB_ORG_OR_REPO_SCOPE] covers an entire org with dozens of repos this could touch many issues at once, overwriting existing assignees and moving issues to In Progress without human review. This side effect is not mentioned in the "When to use this" section or the safety rules.

Suggest adding a warning bullet under "When to use this":

⚠️ Automatically reassigns and moves Linear issues to In Progress for every GitHub issue with an open PR. Verify scope is restricted to your own repositories before enabling org-wide.

[all-hands-bot]

This "prompt" value is itself placeholder/meta text — a user who copy-pastes the curl command as-is will send the literal string "Paste the anonymized prompt above..." to the API, not the actual prompt. The API will accept it but the resulting automation will not do anything useful.

Options:

• Replace with an explicit note above the block: # Replace the prompt value below with the full text from the ## Prompt section above, properly escaped as a JSON string.
• Or inline a truncated hint: "Your full prompt text here (replace with content from the Prompt section above)" — still illustrative but harder to accidentally use verbatim.

[all-hands-bot]

🟡 Acceptable — Well-structured, thoughtful prompt template with solid safety rules. A few usability gaps worth addressing before users run into them.

---

[IMPROVEMENT OPPORTUNITIES]

Missing Linear team/project placeholder (impacts usability)

Task 2 step 3 instructs the agent to "create one in the appropriate Linear team/project," but the Identity and scope section (and the placeholder list in the intro) provides no [LINEAR_TEAM_QUERY] or [LINEAR_PROJECT_QUERY] placeholder. In practice, a workspace with multiple teams (e.g. Backend, Platform, Infra) will cause the agent to guess, which can silently route issues to the wrong team. Adding a placeholder and a corresponding identity line (e.g., - Linear team: resolve by searching for [LINEAR_TEAM_QUERY].) closes this gap cleanly.

Missing prerequisites / required secrets section

The document is self-contained enough to copy-and-paste, but nowhere does it tell users which secrets to configure before the automation can run. A user who sets this up for the first time will hit an auth failure in Task 1's access check without knowing which credential is missing. Recommend adding a short "## Required secrets" or "## Prerequisites" section listing the expected secret names (e.g. GITHUB_TOKEN, LINEAR_API_KEY, SLACK_BOT_TOKEN) and pointing to where to register them in OpenHands.

Implicit Linear assignment / In Progress mutation (undisclosed side effect)

Task 2 step 4 silently assigns the configured Linear assignee and moves issues to In Progress whenever an open PR is associated with them. If [GITHUB_ORG_OR_REPO_SCOPE] spans an entire organization this can touch many issues the user didn't personally open, reassigning them from their current owner. This is a real workflow risk that isn't called out anywhere in the "When to use this" section or the safety rules. Worth at minimum adding a bullet: "Changes Linear issue assignee and status for issues with active PRs — review scope before enabling on org-wide repositories."

Curl example prompt field is placeholder text

The example curl command (line 103) shows "prompt": "Paste the anonymized prompt above after replacing bracketed placeholders." — that string is itself meta-text, not a real value. A first-time user who copy-pastes the command will submit a literal instruction to paste text, not the actual prompt. Options: inline a shortened version of the prompt (with ... ellipsis and a note), or add a comment above the block explaining the user must replace that string with the full prompt text from the section above, properly JSON-escaped or heredoc-embedded.

---

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW
  Documentation-only change. No runtime code is modified. The template itself contains automation instructions that touch real external services (GitHub, Linear, Slack), but those only execute when a user deliberately creates the automation with their own credentials and scope.

VERDICT:
✅ Worth merging — the core structure is sound and the safety rules are genuinely good. The gaps above are quality-of-life improvements for first-time users; they don't block a knowledgeable user from using the template correctly.

KEY INSIGHT:
A missing [LINEAR_TEAM_QUERY] placeholder is the only change that could silently misbehave at runtime — everything else is documentation quality.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing.
2. Re-request a review — the reviewer reads guidelines from the PR branch, so your changes take effect immediately.

Was this review helpful? React with 👍 or 👎 to give feedback.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[all-hands-bot]

The placeholder list includes [GITHUB_USERNAME], [LINEAR_ASSIGNEE_QUERY], [GITHUB_ORG_OR_REPO_SCOPE], [SLACK_RECIPIENT_QUERY], and [IANA_TIMEZONE], but there is no [LINEAR_TEAM_QUERY] (or [LINEAR_PROJECT_QUERY]). Task 2 step 3 will tell the agent to pick "the appropriate Linear team/project" with no guidance, which means it will guess. In multi-team workspaces that silently routes new issues to the wrong team. Suggest adding a placeholder here and a corresponding Identity and scope line such as:

- Linear team: resolve by searching for [LINEAR_TEAM_QUERY]. Do not guess if multiple teams exist.

[all-hands-bot]

"The appropriate Linear team/project" is undefined at this point. The Identity and scope block above (line ~47) specifies assignee and assignee query, but not team. Without a [LINEAR_TEAM_QUERY] placeholder in scope the agent has to infer the team, which is unreliable in workspaces with multiple teams. This line should reference the placeholder once it is added.

[all-hands-bot]

This step silently changes assignee and status on Linear issues the user may not own. If [GITHUB_ORG_OR_REPO_SCOPE] covers an entire org with dozens of repos this could touch many issues at once, overwriting existing assignees and moving issues to In Progress without human review. This side effect is not mentioned in the "When to use this" section or the safety rules.

Suggest adding a warning bullet under "When to use this":

⚠️ Automatically reassigns and moves Linear issues to In Progress for every GitHub issue with an open PR. Verify scope is restricted to your own repositories before enabling org-wide.

[all-hands-bot]

This "prompt" value is itself placeholder/meta text — a user who copy-pastes the curl command as-is will send the literal string "Paste the anonymized prompt above..." to the API, not the actual prompt. The API will accept it but the resulting automation will not do anything useful.

Options:

• Replace with an explicit note above the block: # Replace the prompt value below with the full text from the ## Prompt section above, properly escaped as a JSON string.
• Or inline a truncated hint: "Your full prompt text here (replace with content from the Prompt section above)" — still illustrative but harder to accidentally use verbatim.