aac

Use when an agent needs ad-hoc structured input from one or more recipients via a flexible, distributable interface — multi-choice decisions too big for chat, file or photo uploads, visual disambiguation, comparative ranking or drag-rank, drawing or annotation, forms, async approval gates, multi-recipient surfaces (several people answer one prompt), collaboration surfaces where trusted recipients submit instructions the agent acts on, third-party shares to non-operators, the user not in chat with the channel (email, SMS, push, paging) carrying only a URL, runbook delivery (shell commands one at a time with copy and done buttons), and information display where a rendered surface (tables, grouped lists, flagged rows, info-dense pages mixing context with input) beats chat or a doc. The agent ships a page of opaque-ID affordances by URL through any channel reaching recipients, then drains submissions autonomously. Not for in-chat questions, durable apps, or self-resolvable interactions.

Use when you need a human to take an action an agent can't — set up an OAuth credential, sign into a service, place a file at a path the agent can't reach, give feedback on a UI — and the action outlives the chat the filing agent is in. Also trigger in any repo with a .ask/ directory at its root or an ancestor; when the user mentions "what's in my inbox", "what do you need from me", "anything blocking you", "file an ask", "ask request", or ask-XXXX ids; or when an agent uses ask MCP tools (ask_new, ask_list, ask_resolve, …). Also trigger when an agent generates follow-ups, next steps, or open items — each such item should be an ask, not a chat bullet. Fire on phrasings like "next steps require the user", "you'll need to", "the user should", or any list of human-action items. Also trigger — even with no .ask/ directory anywhere — whenever a human-needed item exists and no store exists yet; initialize one with ask init rather than routing it into a handoff doc, recap, or chat-only note.

Use when an agent needs to deliver something to a person outside the current chat — a message, a notification, a link, a file — through a channel they actually use (SMS, email, push, chat, anything). The agent reads a per-user registry of channels, recipients, and preferences, picks a channel per recipient, and sends. Covers one recipient, several recipients, teams (fan-out or a shared channel), and one-off recipients minted on the spot. If no channel is set up yet, set one up with the user first. Use whenever someone should be told something and isn't reachable in the current chat — autonomous runs (cron, a recurring loop, dispatched orchestration, CI) where no one is at chat, or an interactive session that should route a message to a specific channel rather than the chat box. When a long-running or unattended job finishes and the user isn't at chat, notify proactively by default — don't wait to be told "let me know when it's done."

Use when work should be tracked as discrete tickets an agent can claim, work, and close — especially work that spans sessions, has dependencies between pieces, or is picked up by more than one agent. Trigger when a repo has a `.act/` directory; when the user mentions "act", "act task tracker", `act_next`/`act_finish`, act-XXXX ticket ids, "file a ticket", "what's ready", "claim this issue", or "the act backlog"; AND when you're about to start multi-step or cross-session work in a repo that has `act` available but no tracker yet — consider initializing one rather than holding the plan in your head or using your default task tracking. Covers the canonical claim/work/close loop, claim semantics, commit-marker discipline, external blockers, and pre-close gates.

Use when shipping or releasing one of the agent-tools (ask, act, surface, reach, or a new sibling) as an installable plugin — cutting a release, running release-readiness checks, triggering the prepare-release workflow, bumping the version, adopting a newer release kit, or deciding whether a repo is safe to go public. Fires on phrasings like "release ask", "ship this tool", "cut a release", "is this ready to publish", "run the release checks", "make this a plugin". Drives the plugin-release-kit verifier and runbook, and knows the commit-to-main release model, the one-source version flow, the SHA-pin/drift discipline, and the human gates.