taskboy 0.1.1__py3-none-any.whl

taskboy/task_actions.py

@@ -0,0 +1,86 @@
+"""privileged task controls shared by the dashboard and command-line operator."""
+
+import time
+
+from taskboy.config import Config
+from taskboy.models import BLOCKED, CANCELLED, FAILED, QUEUED, TERMINAL_STATES, Task, utcnow
+from taskboy.orchestrator import accept_task, reopen_issue_and_cancel
+from taskboy.store import Store, TransitionRaced
+
+
+def cancel_task(store: Store, task_id: str, actor: str) -> tuple[Task | None, str]:
+    task = store.get_task(task_id)
+    if task is None:
+        return None, "not found"
+    if task.state in TERMINAL_STATES:
+        store.add_event(task_id, "operator_action", {"actor": actor, "action": "cancel", "outcome": "noop", "state": task.state})
+        return task, f"already {task.state}"
+    try:
+        cancelled = store.transition(task_id, task.state, CANCELLED, f"cancelled via dashboard by {actor}", finished_at=utcnow())
+    except TransitionRaced:
+        current = store.get_task(task_id)
+        if current is not None:
+            store.add_event(task_id, "operator_action", {"actor": actor, "action": "cancel", "outcome": "raced", "state": current.state})
+        return current, f"already {current.state}" if current else "not found"
+    store.add_event(task_id, "operator_action", {"actor": actor, "action": "cancel", "outcome": "cancelled", "previous_state": task.state})
+    return cancelled, "cancelled"
+
+
+async def retry_task(store: Store, config: Config, notifier, source_task_id: str, actor: str) -> tuple[Task | None, str]:
+    source = store.get_task(source_task_id)
+    if source is None:
+        return None, "not found"
+    if source.state not in (FAILED, CANCELLED):
+        store.add_event(source_task_id, "operator_action", {"actor": actor, "action": "retry", "outcome": "rejected", "state": source.state})
+        return source, f"cannot retry {source.state}"
+    if (source.request_text or "").startswith("/spec2pr "):
+        # an issue-backed task's issue is already back to `proposed` with no spec by the time it's terminal (#76)
+        store.add_event(source_task_id, "operator_action", {"actor": actor, "action": "retry", "outcome": "rejected", "state": source.state, "reason": "issue_backed"})
+        return source, "cannot retry an issue-backed task — re-approve its issue instead"
+    retried, status = await accept_task(
+        store,
+        config,
+        notifier,
+        team_id=source.slack_team_id,
+        channel_id=source.slack_channel_id,
+        thread_ts=source.slack_thread_ts,
+        message_ts=str(time.time_ns()),
+        user_id=actor,
+        text=source.request_text,
+        parent_task_id=source.task_id,
+        model_override=source.model_override,
+        effort_override=source.effort_override,
+        thread_context=source.thread_context,
+        debug_thread_ts=source.debug_thread_ts,
+        debug_permalink=source.debug_permalink,
+    )
+    store.add_event(source_task_id, "operator_action", {"actor": actor, "action": "retry", "outcome": status, "new_task_id": retried.task_id if retried else None})
+    return retried, status
+
+
+async def decide_permission(store: Store, notifier, task_id: str, kind: str, target: str, decision: str, actor: str) -> tuple[Task | None, str]:
+    """grant or deny a sub-agent's permission request: granting a blocked task resumes it, denying reopens and cancels its issue-backed task instead of stranding it (#76)."""
+    if decision not in ("granted", "denied"):
+        return None, "decision must be granted or denied"
+    task = store.get_task(task_id)
+    if task is None:
+        return None, "not found"
+    row = store.decide_permission_request(task_id, kind, target, decision, actor)
+    if row is None:
+        store.add_event(task_id, "operator_action", {"actor": actor, "action": f"permission_{decision}", "outcome": "no pending request", "kind": kind, "target": target})
+        return task, "no pending request"
+    store.add_event(task_id, "permission_decision", {"actor": actor, "decision": decision, "kind": kind, "target": target})
+    # re-read: the task may have settled into BLOCKED since we first fetched it. if it is still RUNNING, the
+    # orchestrator will pick up this grant when the session ends (run-start grant snapshot diff), so we leave it be here.
+    task = store.get_task(task_id) or task
+    if task.state == BLOCKED:
+        if decision == "granted":
+            try:
+                task = store.transition(task_id, BLOCKED, QUEUED, f"resumed after permission granted by {actor}", resume_session_id=task.session_id)
+            except TransitionRaced:
+                pass
+        elif not store.has_pending_permission_request(task_id):
+            # no other request is still pending on this task; an issue-backed task must not strand its issue in_progress forever (#76)
+            if await reopen_issue_and_cancel(store, notifier, task):
+                task = store.get_task(task_id) or task
+    return task, decision

taskboy/templates/config.example.yaml

@@ -0,0 +1,149 @@
+# taskboy operator config. copy to config.yaml (local dev) or /etc/taskboy/config.yaml (host).
+# config.yaml is gitignored in this repo template — commit it to your own private fork/repo if you want it version-controlled.
+# apply changes with a service restart — restarts are safe, running tasks are requeued and resumed.
+# tip: run `taskboy setup` for a guided walkthrough that fills this file in for you.
+#
+# connected services (slack, github, jira, confluence, sentry, aws) each live in their own file
+# under services/<name>.yaml next to this file, with an explicit enabled flag — turn a service
+# on or off there without touching this file.
+
+orchestrator:
+  max_concurrency: 3 # max sub-agents running at once (ORC-005)
+  queue_max: 20 # tasks waiting beyond this are refused with a clear reply (ORC-006)
+  max_retries: 2 # restart/requeue attempts before a task is failed (REL-003)
+  progress_min_interval_seconds: 60 # per-task floor between slack progress posts (SLK-006)
+  runner: echo # echo (dev, no model calls) | claude (real sub-agent sessions; needs CLAUDE_CODE_OAUTH_TOKEN)
+
+agent: # the main agent's identity
+  name: Agent # display name used in slack, prompts, PR/Jira text, and the dashboard
+  personality_file: "" # e.g. personality_agent.md, relative to this config file; empty = neutral voice; configured files must exist at startup
+
+reviewer: # optional second GitHub-only persona that reviews the main agent's PRs (needs its own GitHub App)
+  enabled: false
+  name: Reviewer
+  personality_file: "" # e.g. personality_reviewer.md; configured files must exist at startup
+  review_agent_prs: true # auto-review PRs authored by the main agent
+  commit_name: "" # git author on the reviewer's commits; empty = defaults to reviewer name
+  # GitHub derives the commit avatar from this email; verify it on a GitHub account to give the reviewer a custom avatar (operator-side setup)
+  commit_email: "" # required when enabled
+
+classifier:
+  tier: haiku # model alias used for the single classification call
+
+cli_update: # off-peak upgrade of the claude-agent-sdk package (bundles the claude cli) + service restart, ungated by ci
+  enabled: false # the service self-restarts after a pip upgrade via the flag-file + taskboy-restart.path unit from the packaged install.sh
+  at_time: "02:00" # HH:MM, local to tzname
+  tzname: America/Los_Angeles
+
+issues: # multi-repo issue discovery, refinement, discussion, and implementation
+  notify_channel: "" # optional slack channel id for lifecycle posts on manual issue runs
+  uploads_bucket: "" # empty = comment attachments disabled (local dev)
+  # recurring discovery/implementation runs are seeded as editable schedules on the dashboard Scheduler page
+
+skills: # model + execution profile for /skill-name invocations; tier must be in the models catalog
+  tier: opus # change here to move all skill runs
+  profile: standard
+
+roles: # use members: ["*"] on at most one role to allow anyone in an allowed channel
+  admin:
+    members: [YOUR_SLACK_USER_ID, cli]
+    allowed_profiles: [read_only, standard, deep]
+    model_override: true
+    max_budget_usd: null
+  developer:
+    members: []
+    allowed_profiles: [read_only, standard, deep]
+    model_override: false
+    max_budget_usd: 12.0
+  readonly:
+    members: []
+    allowed_profiles: [read_only]
+    model_override: false
+    max_budget_usd: 2.0
+  system:
+    members: [github]
+    allowed_profiles: [read_only, standard]
+    model_override: false
+    max_budget_usd: 12.0
+
+models: # catalog aliases -> model ids; swap here, never in code (MOD-007)
+  # the cli resolves haiku/sonnet/opus to current models; pin full ids here if you need version stability
+  haiku: { id: haiku, fallbacks: [sonnet] }
+  sonnet: { id: sonnet, fallbacks: [opus] }
+  opus: { id: opus, fallbacks: [] }
+  fable: { id: claude-fable-5, fallbacks: [opus] }
+
+routing: # first match wins; fields ANDed, values within a field ORed (MOD-002)
+  rules:
+    - { name: cheap-questions, match: { task_type: [question, investigation], complexity: [trivial] }, tier: haiku, profile: read_only }
+    - { name: critical-work, match: { complexity: [critical] }, tier: fable, profile: deep }
+    - { name: complex-work, match: { complexity: [complex] }, tier: opus, profile: deep }
+    - { name: standard-eng, match: { task_type: [bug_fix, feature, pr_review, incident_diagnosis, jira_ops] }, tier: sonnet, profile: standard }
+  default: { tier: sonnet, profile: read_only }
+
+profiles: # budgets + tool allowlists per risk level (ORC-009, §11)
+  read_only:
+    # bash is needed for investigation (clone, grep, run tests); hooks police it and read_only sessions get read-only github tokens
+    allowed_tools: [Read, Grep, Glob, Bash, WebFetch, ToolSearch, mcp__harness__report_progress, mcp__harness__report_blocked, mcp__harness__request_permission, mcp__harness__ask_questions, mcp__github__get_pull_request, mcp__github__list_pull_requests, mcp__github__list_pr_files, mcp__github__list_pr_comments, mcp__jira__search_issues, mcp__jira__search_users, mcp__jira__get_issue, mcp__jira__list_boards, mcp__jira__list_sprints, mcp__sentry__list_issues, mcp__sentry__get_issue, mcp__sentry__get_latest_event, mcp__aws__aws_read, mcp__slack__channel_history, mcp__slack__thread_replies, mcp__slack__user_info, mcp__slack__get_file, mcp__confluence__search_pages, mcp__confluence__get_page]
+    max_budget_usd: 2.0
+    max_turns: 60
+    max_runtime_minutes: 30
+    effort: low
+  standard:
+    allowed_tools: [Read, Grep, Glob, Bash, WebFetch, ToolSearch, Write, Edit, mcp__harness__report_progress, mcp__harness__report_blocked, mcp__harness__request_permission, mcp__harness__ask_questions, mcp__github__get_pull_request, mcp__github__list_pull_requests, mcp__github__list_pr_files, mcp__github__list_pr_comments, mcp__github__create_pull_request, mcp__github__comment_on_pull_request, mcp__github__create_pr_review, mcp__github__reply_to_pr_comment, mcp__github__resolve_pr_thread, mcp__github__close_pull_request, mcp__github__delete_branch, mcp__github__create_release, mcp__jira__search_issues, mcp__jira__search_users, mcp__jira__get_issue, mcp__jira__list_boards, mcp__jira__list_sprints, mcp__sentry__list_issues, mcp__sentry__get_issue, mcp__sentry__get_latest_event, mcp__aws__aws_read, mcp__jira__create_issue, mcp__jira__add_comment, mcp__jira__assign_issue, mcp__jira__transition_issue, mcp__jira__move_to_sprint, mcp__jira__set_epic, mcp__jira__set_story_points, mcp__jira__link_pr, mcp__slack__channel_history, mcp__slack__thread_replies, mcp__slack__user_info, mcp__slack__get_file, mcp__slack__send_dm, mcp__confluence__search_pages, mcp__confluence__get_page]
+    max_budget_usd: 12.0
+    max_turns: 400
+    max_runtime_minutes: 240
+  deep:
+    allowed_tools: [Read, Grep, Glob, Bash, WebFetch, ToolSearch, Write, Edit, mcp__harness__report_progress, mcp__harness__report_blocked, mcp__harness__request_permission, mcp__harness__ask_questions, mcp__github__get_pull_request, mcp__github__list_pull_requests, mcp__github__list_pr_files, mcp__github__list_pr_comments, mcp__github__create_pull_request, mcp__github__comment_on_pull_request, mcp__github__create_pr_review, mcp__github__reply_to_pr_comment, mcp__github__resolve_pr_thread, mcp__github__close_pull_request, mcp__github__delete_branch, mcp__github__create_release, mcp__jira__search_issues, mcp__jira__search_users, mcp__jira__get_issue, mcp__jira__list_boards, mcp__jira__list_sprints, mcp__sentry__list_issues, mcp__sentry__get_issue, mcp__sentry__get_latest_event, mcp__aws__aws_read, mcp__jira__create_issue, mcp__jira__add_comment, mcp__jira__assign_issue, mcp__jira__transition_issue, mcp__jira__move_to_sprint, mcp__jira__set_epic, mcp__jira__set_story_points, mcp__jira__link_pr, mcp__slack__channel_history, mcp__slack__thread_replies, mcp__slack__user_info, mcp__slack__get_file, mcp__slack__send_dm, mcp__confluence__search_pages, mcp__confluence__get_page]
+    max_budget_usd: 20.0
+    max_turns: 400
+    max_runtime_minutes: 240
+    effort: high
+    thinking: { type: adaptive }
+
+quick_answer:
+  enabled: true
+  tier: haiku
+  timeout_seconds: 20
+  max_per_user_per_hour: 30
+
+usage_limits: # total-token ceilings for dashboard remaining-capacity meters; zero disables a meter
+  five_hour_tokens: 0
+  weekly_tokens: 0
+  fable_weekly_tokens: 0
+
+conventions: # engineering conventions doc injected into repo-targeting task workspaces as CONVENTIONS.md
+  file: "" # e.g. conventions.md, relative to this config file's directory; empty = disabled
+
+help: # curated `/help` reply text; re-read on every request, editable in the dashboard
+  file: "" # e.g. help.md, relative to this config file's directory; empty disables the /help fast path entirely
+
+dashboard: # web ui; served behind an alb doing sso in deployed envs
+  enabled: false
+  bind: 127.0.0.1 # 0.0.0.0 on the host (the security group only admits the alb)
+  port: 8787
+  allowed_email_domain: "" # required when enabled; read-only access for any account under this domain, e.g. example.com
+  public_url: "" # e.g. https://agent.example.com; empty disables dashboard links in slack posts
+  admin_emails: [] # management surface: editing, cancel/retry
+  dev_user_email: dev@example.com # local-only stand-in identity when no alb header is present
+  expected_alb_arn: "" # required when enabled: true; must match the oidc header's "signer" claim
+  auto_commit: # empty repo disables committing dashboard edits back to git
+    repo: "" # org/repo that holds this config
+    branch: main
+    committer_name: "" # git committer identity on dashboard auto-commits; empty = "<agent name> Dashboard"
+    committer_email: "" # required when repo is set
+
+audit: # hourly jsonl shipping of the hash-chained event trail (§10); empty bucket = disabled (local dev)
+  bucket: ""
+
+retention: # days (MEM-012, §12)
+  workspace_completed_days: 3
+  workspace_failed_days: 7
+  memory_days: 90
+  audit_days: 365
+  slack_events_days: 7
+  errors_days: 30 # errors.traceback/context_json rows can be multi-KB; not hash-chained, safe to purge
+  # usage, admin_events, and task_events are kept forever
+  blocked_task_max_days: 10 # a task stuck BLOCKED (unanswered questions/permission request) this long auto-fails
+  blocked_task_reminder_days: 5 # thread reminder posted partway through the blocked_task_max_days window

taskboy/templates/conventions.md

@@ -0,0 +1,60 @@
+# Engineering Conventions
+
+<!--
+This file is your organization's ground truth for how code should be written, tested,
+and shipped. When a task targets one of your repositories, the harness copies this file
+into the agent's workspace as CONVENTIONS.md and instructs the agent to read and follow
+it before writing, changing, or reviewing any code. The /review skill judges pull
+requests against it.
+
+How to set it up:
+  1. Copy this file to config/conventions.md (or any path you like).
+  2. Point conventions.file at it in config.yaml (path is relative to config.yaml).
+  3. Fill in the sections below. Delete any section that doesn't apply.
+
+Writing tips:
+  - Be concrete. "Use pytest, tests live in tests/, mirror the source layout" beats
+    "write good tests".
+  - State the *why* for rules that would otherwise be argued with.
+  - Keep it under ~250 lines — the agent reads this on every repo task.
+-->
+
+## Stack & shared libraries
+
+<!-- The languages, frameworks, and internal libraries your services are built on,
+     with pinned versions where they matter. Example:
+     "Services are Python 3.12 + FastAPI. All services use our shared `acme-lib`
+     (pin the latest tag, currently 2.4.1) for auth, logging, and DB sessions." -->
+
+## Code style & values
+
+<!-- The taste rules that make code reviewable in your org. Example:
+     "Keep it simple: write logic out longhand rather than clever or DRY.
+     Comments are short, lowercase, and explain why — not what the line does." -->
+
+## Project layout
+
+<!-- What a well-formed repo looks like: the directory skeleton, what goes where,
+     and when to add (or not add) new folders. -->
+
+## Testing
+
+<!-- Which test tiers exist, which are required, how they run, and what a good test
+     looks like. Example: "Every service ships end-to-end tests under
+     tests/e2e/ that hit a live deployed instance; unit tests only for pure logic." -->
+
+## Checks & CI
+
+<!-- The commands that must pass before pushing (e.g. `make check`), and what CI
+     enforces on pull requests. -->
+
+## Review bar
+
+<!-- What a reviewer (human or agent) should block on vs. let slide.
+     Example: "Block on correctness, security, and missing tests. Don't block on
+     style that the formatter accepts." -->
+
+## Branching, releases & deployment
+
+<!-- Branch naming, protected branches, how releases are cut, and where things deploy.
+     Example: "PRs target develop; a v*.*.* tag on main deploys to production." -->

taskboy/templates/help.example.md

@@ -0,0 +1,29 @@
+# curated `/help` reply, answered instantly without creating a task.
+# copy to help.md (the setup wizard fills in the placeholders and drops these comment lines),
+# point help.file at it in config.yaml, and trim it to the skills you actually installed.
+
+Here's how to work with {{agent_name}}:
+
+• Mention `@{{agent_name}}` in an allowlisted channel, or in a DM, to start a task. A DM without a mention gets a quick chat reply instead — it won't start a task.
+• Plain-English requests are classified and routed to the right skill automatically — no slash needed.
+• A slash invocation runs one skill directly, skipping classification, e.g. `@{{agent_name}} /review {pr_url}`.
+• Mentioning `@{{agent_name}}` again inside an existing task's thread continues that same task as a follow-up. A plain reply (no mention) is ignored unless the task is waiting on your answer to a question.
+• If {{agent_name}} needs more information it will ask; if it can't proceed it will say why instead of guessing.
+
+Dashboard: {{dashboard_url}}
+
+Slash skills:
+• `/discoverissues {owner/repo}` — investigate a repo and record ranked issues for review.
+• `/refineissue {issue_id}` — reconcile an issue's discussion with the current repo and sharpen it for implementation.
+• `/jira2pr {ticket_id} {context}` — implement a Jira ticket and open a PR.
+• `/slack2jira {slack_thread_url} {context}` — turn a Slack thread into a Jira ticket.
+• `/slack2pr {slack_thread_url} {context}` — turn a Slack thread directly into a PR, no ticket in between.
+• `/review {pr_url}` — review one GitHub PR for simplicity and correctness.
+• `/reviews {pr_url ...|repo}` — run /review across many PRs at once.
+• `/monitor {pr_url}` — watch a PR for changes for up to 3 hours and re-review on each one.
+• `/monitornew {repo}` — watch a repo for its next new PR and review it when it appears.
+• `/reviewandmonitor {pr_url}` — review a PR now, then keep watching it.
+• `/release` — cut a new release of the agent's own repo with notes sized to the changes since the last tag.
+• `/implementapprovedissues` — turn the day's approved issue batch into specs and enqueue one PR task per issue.
+
+That's not the full skill list — ask an admin, or check the `SKILL.md` files under `skills/`, for anything not covered here.

taskboy/templates/personality_agent.example.md

@@ -0,0 +1,5 @@
+# the main agent's voice, used only for requester-facing replies (never internal reports).
+# copy to personality_agent.md, point agent.personality_file at it in config.yaml, and make it yours.
+# keep it short — a few sentences of tone guidance beats a page of rules.
+
+Plainspoken and direct. Answer first, context second. No filler, no corporate cheer.

taskboy/templates/personality_reviewer.example.md

@@ -0,0 +1,5 @@
+# the reviewer persona's voice, used in PR review comments.
+# copy to personality_reviewer.md, point reviewer.personality_file at it in config.yaml, and make it yours.
+
+Courteous and exact. Every finding names the file and line, states the failure it causes,
+and suggests a concrete fix. Approve promptly when the code is sound — silence is not a review.

taskboy/templates/services/aws.yaml

@@ -0,0 +1,7 @@
+# aws service — read-only diagnostics; writes are denied by IAM and by the adapter (AWS-004/005).
+enabled: false # true requires at least one entry in allowed_services
+allowed_services: [] # e.g. [logs, cloudwatch, lambda, ecs, s3]
+allowed_regions: [us-east-1]
+# diagnostics_role_arns: # per-environment roles the agent assumes for reads; comment out for local-dev default creds
+#   staging: arn:aws:iam::YOUR_ACCOUNT_ID:role/your-staging-diagnostics-role
+#   production: arn:aws:iam::YOUR_ACCOUNT_ID:role/your-production-diagnostics-role

taskboy/templates/services/confluence.yaml

@@ -0,0 +1,4 @@
+# confluence service — read-only page search/fetch (uses the jira service account credentials).
+enabled: false # true requires site below plus JIRA_EMAIL / JIRA_API_TOKEN in the environment
+site: "" # e.g. https://your-org.atlassian.net
+spaces: [] # empty = any space the service account can read

taskboy/templates/services/github.yaml

@@ -0,0 +1,14 @@
+# github service — git push auth, pull request tools, review-request polling, and the issues pipeline.
+enabled: false # true requires the GitHub App credentials (GITHUB_APP_ID / GITHUB_INSTALLATION_ID / GITHUB_APP_PRIVATE_KEY)
+approved_repos: [] # org/repo
+self_repo: "" # org/repo of this agent's own source; must also be in approved_repos; empty = no self-repo hint
+protected_branch_patterns: [main, develop]
+commit_name: "" # git author/committer on commits the agent pushes; empty = defaults to agent.name
+# GitHub derives the commit avatar from this email; verify it on a GitHub account to give the agent a custom avatar (operator-side setup)
+commit_email: ""
+review_requests: # poll approved repos for PRs where the agent is a requested reviewer -> run /review
+  enabled: false
+  poll_interval_seconds: 60
+  notify_channel: "" # optional slack channel id for lifecycle updates on github-triggered reviews
+  auto_address_agent_prs: false # when true, an unresolved (non-APPROVE) reviewer review on an agent-authored PR auto-spawns the agent to address it
+  round_cap: 10 # max agent<->reviewer rounds per PR before the loop stops and escalates instead of continuing

taskboy/templates/services/jira.yaml

@@ -0,0 +1,6 @@
+# jira service — issue reads and writes through the jira mcp tools.
+enabled: false # true requires site below plus JIRA_EMAIL / JIRA_API_TOKEN in the environment
+site: "" # e.g. https://your-org.atlassian.net
+projects: [] # project keys the agent may touch, e.g. [ENG]
+issue_types: [Story, Bug, Task]
+story_points_field: "" # e.g. customfield_10016; empty = story points not set

taskboy/templates/services/sentry.yaml

@@ -0,0 +1,4 @@
+# sentry service — read-only issue and event lookups.
+enabled: false # true requires organization below plus SENTRY_TOKEN in the environment
+organization: "" # sentry org slug
+projects: []

taskboy/templates/services/slack.yaml

@@ -0,0 +1,9 @@
+# slack service — socket-mode intake and notifications.
+# each connected service lives in its own file under services/ so it can be turned on or off here
+# without touching config.yaml. apply changes with a service restart.
+enabled: false # true requires team_id below plus SLACK_BOT_TOKEN / SLACK_APP_TOKEN in the environment
+team_id: "" # workspace id (T…)
+debug_channel: "" # set to a private debug channel id; empty disables the debug feed
+task_started_messages_file: task_started_messages.yaml # relative to config.yaml; missing/invalid uses legacy text
+allowed_channels: [] # channel ids, e.g. [C0123ABCDEF]; empty = any channel the bot is invited to
+ack_reaction: true # 👀 reaction instead of the "On it" message; false restores the text ack

taskboy/templates/skills/README.md

@@ -0,0 +1,33 @@
+# Skill templates
+
+These directories are **templates**, not installed skills. The agent never loads them directly — they are instantiated into the top-level `skills/` directory, either by the `taskboy setup` wizard (the skills picker step fills in every variable from your answers) or by hand:
+
+1. Copy the template directory into `skills/` (keep the `<name>/SKILL.md` layout).
+2. Replace every `{{variable}}` placeholder in the copied `SKILL.md` with your value. No placeholder may remain — the loader does not substitute variables at runtime.
+
+## Variables
+
+| Variable | Meaning | Example |
+| --- | --- | --- |
+| `{{agent_name}}` | Main agent display name | `Scout` |
+| `{{reviewer_name}}` | Reviewer persona display name | `Critic` |
+| `{{github_org}}` | GitHub org bare repo names resolve against | `example-org` |
+| `{{repo_list}}` | Comma-separated backtick list of repos the agent may work in | `` `svc-a`, `svc-b` `` |
+| `{{self_repo}}` | The agent's own repository (`owner/repo`) | `example-org/taskboy` |
+| `{{pr_target_branch}}` | Default PR target / integration branch | `main` |
+| `{{jira_project}}` | Jira project key | `ENG` |
+| `{{jira_site}}` | Jira site host | `example.atlassian.net` |
+| `{{conventions_file}}` | Repo-relative path to the engineering conventions doc (`conventions.file` in config.yaml) | `config/conventions.md` |
+
+Not every template uses every variable — replacing all of them is always safe.
+
+## Frontmatter
+
+Each `SKILL.md` starts with YAML frontmatter:
+
+- `name` (required) — must equal the directory name exactly; the loader rejects a mismatch.
+- `description` (required) — one line shown in skill listings and used for routing.
+- `requires` (optional) — list of other skill names whose bodies get inlined when this skill runs; the required skills must be installed too.
+- `model` (optional) — model alias the skill runs on; must be an alias defined in the model catalog in config.yaml (e.g. `fable`, `opus`, `sonnet`).
+- `profile` (optional) — execution profile override.
+- `internal_tools` (optional) — in-process capability servers the skill opts into (currently `issues`, `enqueue`).

taskboy/templates/skills/discoverissues/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: discoverissues
+description: Investigate one approved repository and record ranked issues for operator review. Invoked as `@{{agent_name}} /discoverissues {owner/repo}`.
+model: fable
+profile: standard
+internal_tools: [issues]
+---
+
+# discoverissues
+
+Discover concrete, code-grounded issues in one repository. Record proposals only; never open a PR here.
+
+The first argument is the required `owner/repo`. If it is missing, call `report_blocked` asking for it and stop. Call `list_existing_issues` with that repo before investigating; if the tool rejects the repo as unapproved, call `report_blocked` with the allowed repositories from the error and stop.
+
+## Step 1 — Gather evidence
+
+Always inspect existing issues for this repo so you do not duplicate proposed, approved, denied, active, or completed work.
+
+For `{{self_repo}}`, also use `list_task_feedback`, `list_failed_tasks`, and `list_recent_errors` (limit 200) to study real task failures and recurring internal errors. For every other repo, ground findings in its current code, open pull requests/issues context available through GitHub tools, and recent `git log` history.
+
+Every tool response is capped around 4000 characters and truncates silently past that. `list_existing_issues` takes `offset` and `status` to page through the full table (add `keys_only: true` for compact id/dedupe_key/status rows when you just need to check for duplicates), and `list_recent_errors` takes `offset`, `component`, and `kind` to page to a specific recurring error and control the traceback tail length with `traceback_chars`. `list_failed_tasks` takes `offset`, `task_type`, and `query`. `list_task_feedback` takes `offset`. Make repeated calls with `offset` until a call returns fewer rows than `limit` to see the whole backlog.
+
+## Step 2 — Read the repository
+
+Clone the requested repo and read enough source, tests, conventions, and recent history to verify every finding. Prefer a small number of high-impact findings over speculation. Look for user-facing gaps, bugs, security weaknesses, reliability failures, performance problems, and code that is needlessly difficult to change.
+
+## Step 3 — Record issues
+
+Call `record_issue` once per distinct finding with:
+
+- `repo`: the exact requested `owner/repo`.
+- `summary`: one concise title.
+- `issue_type`: use `feature_request`, `bug`, `security`, `user_experience`, `reliability`, `performance`, `token_efficiency`, or `organization` where applicable.
+- `details`: markdown explaining what should change, where, why, evidence, acceptance checks, and risks.
+- `dedupe_key`: a stable repo-qualified kebab-case slug. Reuse an existing proposed issue's exact key only when refreshing it.
+- `priority`: 1–100 based on impact and frequency.
+
+Do not re-propose denied or completed work. Recording the same key only refreshes a proposed row.
+
+## Reply
+
+In 1–3 sentences, say how many issues you recorded, name the top one or two, and say they await dashboard review.
+
+## Final Report
+
+List the repo, every recorded id/key/type/priority, the main evidence, anything you could not verify, and one short line per tool failure.

taskboy/templates/skills/implementapprovedissues/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: implementapprovedissues
+description: Turn the reserved batch of approved multi-repo issues into grounded specs and enqueue one PR task per issue. Invoked as `@{{agent_name}} /implementapprovedissues`.
+model: fable
+profile: standard
+internal_tools: [issues, enqueue]
+---
+
+# implementapprovedissues
+
+Turn the current reserved issue batch into implementation specs, then hand each spec to `/spec2pr` with `enqueue_spec_pr`. Do not open PRs yourself.
+
+## Step 1 — Load the batch
+
+Call `list_accepted_issues`. It returns up to five issues reserved for this coordinator, including each issue's target `repo`. If there are none, reply that nothing was approved and stop — do not call `report_blocked`; an empty queue is a normal daily outcome.
+
+Clone each distinct target repo as needed. A batch may span repositories; never assume an issue targets `{{self_repo}}`.
+
+## Step 2 — Write repo-specific specs
+
+For every issue in priority order, verify its description against the current target repo. Skip work that is already complete or no longer applies and explain why in the final report.
+
+Each markdown spec must explicitly name the target repo and include:
+
+- Goal and rationale tied to the issue.
+- Concrete files/areas and changes.
+- Tests and validation commands.
+- Existing repository conventions and compatibility constraints.
+- The smallest acceptable scope and explicit non-goals.
+
+## Step 3 — Enqueue PR work
+
+Call `enqueue_spec_pr` once per verified issue with its id and full spec. The child `/spec2pr` task reads the issue's repo, implements the spec there, opens a PR, and records the result. Do not wait for child tasks.
+
+## Reply
+
+In 1–3 sentences, report how many specs were enqueued and which issue ids/repos they target.
+
+## Final Report
+
+List each issue and child handoff, skipped issues and reasons, and one short line per tool failure.

taskboy/templates/skills/jira2pr/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: jira2pr
+description: Read a {{jira_project}} Jira ticket (and its linked Slack thread, if any) and open a PR that implements it. Invoked as `@{{agent_name}} /jira2pr {ticket_id} {context}` — ticket_id is the bare number (e.g. `514`); context may name the repo. Solutions must be the simplest thing that works (KISS + YAGNI).
+---
+
+# jira2pr
+
+Turn a **{{jira_project}}** ticket into a pull request.
+
+- The first argument is the ticket id, a **bare number** like `514`. Prepend `{{jira_project}}-` to get the key (`{{jira_project}}-514`). Tolerate the full key or its lowercase form too.
+- The rest of the arguments are free-form context. Parse for intent — most importantly a **repo hint**, plus any implementation notes.
+
+If the ticket id is missing, call `report_blocked` asking for it, then stop.
+
+Don't pre-check auth or tool availability — just call the tool. If it fails, note it in the Final Report.
+
+## Keep it simple
+
+Simplest thing that works — KISS + YAGNI:
+
+- **Do the least** — fewest lines, files, concepts. No new abstractions, files, folders, config, or options "for later" unless the ticket genuinely can't be done without them.
+- **No fluff** — no comments restating the code, no docstrings on obvious methods, no defensive/speculative scaffolding.
+- **Match neighboring code** and the repo's existing conventions (see the workspace `CONVENTIONS.md` when present): longhand over clever/DRY. Mirror idioms; don't invent.
+- **Err hard toward under-building** — too-simple gets flagged on review, not the reverse.
+
+## Step 1 — Read the ticket
+
+Fetch `{{jira_project}}-{id}` with `mcp__jira__get_issue`. Pull: summary, description, status, assignee, and any linked URLs. Use `mcp__jira__search_issues` if you need the parent epic for context.
+
+If the description contains a **Slack thread link**, read that thread with `mcp__slack__thread_replies` (resolve the channel id and thread timestamp from the URL — `p1234567890123456` becomes `1234567890.123456`). This only works for channels {{agent_name}} is allowed in; if it fails, note it and continue with the ticket alone.
+
+Boil it down to: what needs to change, and the smallest change that satisfies it.
+
+## Step 2 — Decide the repo
+
+The work happens in one of the repos in the `{{github_org}}` org: {{repo_list}}.
+
+- If the **context names a repo**, use it.
+- Otherwise infer from the ticket (which service/domain the work clearly belongs to).
+- **If you're not confident, call `report_blocked` asking which repo, then stop.** Don't guess on this.
+
+The repo may already be cloned in your workspace; otherwise `git clone https://github.com/{{github_org}}/{repo}` (auth is handled).
+
+## Step 3 — Implement (simplest possible)
+
+1. Branch off **`{{pr_target_branch}}`** (the integration branch and the PR target). Name the branch per {{agent_name}}'s convention with the ticket key: `agent/{task_id}-{lowercase_ticket_key}-short-slug`.
+2. Make the **smallest change that satisfies the ticket.** Re-read "keep it simple" before you write a line. Prefer editing existing files; prefer a few lines over many.
+3. Follow the repo's existing patterns exactly. No new deps, no version bumps, no reformatting unrelated lines, no drive-by cleanups.
+4. Add a test **only** if the ticket's logic warrants it, following the repo's testing conventions.
+
+## Step 4 — Open the PR
+
+Commit, push the branch, and open a PR **targeting `{{pr_target_branch}}`** with `mcp__github__create_pull_request`.
+
+- **Title**: short — the ticket key + a terse description, e.g. `{{jira_project}}-514: fix pagination on the exports list`.
+- **Body**: the required Summary, Testing performed, and Known limitations sections — each terse — plus the ticket link (`https://{{jira_site}}/browse/{{jira_project}}-{id}`).
+
+Opening the PR automatically triggers a review by {{reviewer_name}}, the reviewer persona (when enabled) — no action is needed, and don't wait for it.
+
+Then attach the PR to the ticket with `mcp__jira__link_pr`.
+
+Open it directly when the repo and scope are clear. Call `report_blocked` only if the ticket is too underspecified to implement.
+
+## Final Report
+
+The PR URL on its own line. One short line per failure. Nothing else.

taskboy/templates/skills/monitor/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: monitor
+description: Watch a GitHub PR for up to 3 hours, checking every 5 minutes for new pushes or new comments from the PR author; on any change, re-run the /review procedure on it. Invoked as `@{{agent_name}} /monitor {pr_url}`.
+requires: [review]
+---
+
+# monitor
+
+Watch a GitHub PR and re-review it every time it changes, for up to 3 hours (your session has a hard runtime limit — never plan past it).
+
+The first GitHub PR URL in the arguments is the PR to watch. If it is missing, call `report_blocked` asking for it, then stop.
+
+A "change" is either a **new push** (the PR head SHA moved) or a **new comment from the PR author** (issue or review comment authored by the PR author). Comments you ({{agent_name}}) leave don't count — only the author's.
+
+An author comment counts **even when it's just "done"** with no new push. Never skip the re-review as redundant — a "done" with the code unchanged is exactly what the review's reconciliation step exists for: it confirms whether "done" is actually done, and re-flags if it isn't.
+
+## The loop
+
+Keep watch state in a file at `../notes/monitor.json` (your workspace's notes directory): `end_time` (epoch seconds), `head_sha`, `last_author_comment_ts`.
+
+1. **Baseline** — fetch the PR with `mcp__github__get_pull_request` (note `head_sha`) and the latest author comment timestamp from `mcp__github__list_pr_comments` called with `author` set to the PR author's login. Compute `end_time` = now + 10800 (3 hours). Write the state file. Post one `report_progress`: `monitoring {repo}#{n} — checking every 5 min for up to 3h`. Do **not** review at baseline.
+2. **Tick** — wait 5 minutes using Bash sleeps in chunks no longer than 100 seconds (`sleep 100` three times); a single long sleep will hit the command timeout. Then:
+   - If now ≥ `end_time`, or the PR is closed/merged: stop the loop and write the Final Report.
+   - Fetch the current head SHA, and call `mcp__github__list_pr_comments` with `author` set to the PR author's login to check cheaply for anything new from them — the newest author comment is always the last line. It counts as new only if its `created_at` is **strictly greater than** `last_author_comment_ts`, not merely if the result is non-empty.
+   - **Changed** (head moved, or a newer author comment, per the strictly-greater check above): run the included `/review` procedure end to end, then update the state file and post `report_progress`: `reviewed — left N comments`.
+   - **Not changed**: do nothing (no progress post) and continue.
+
+Keep per-tick work minimal — two tool calls and a comparison.
+
+## Final Report
+
+How long you watched, how many ticks ran, and each re-review with its comment count. Nothing else.