awaywork

Appearance

Posts that wait and threads ​

Posts that wait ​

A deliver: report rule with wait: true posts its result on the item and waits for your answer there, like a plan; your approve hands the item to the next stage. Plans wait by default (wait: false lets one go ahead); reports don't.

yaml
queue:
  - skill: story
    where: { section: Inbox }
    deliver: report
    wait: true # your approve hands it to the next rule
    on_done: { move: Ready for design } # held until you approve
  - skill: prototype
    where: { approved: story } # works on a tracker that can't move cards too
    deliver: report
    gates:
      taste: { skill: judge, instructions: [judges/design.md] } # one that fires holds the post

The post is the result as on_done: { comment: result } writes it, asked for or not, with how to answer and its state on the mark line:

Result of story

Export VAT as CSV from the reports page.

Status: done

To approve, reply with approve as the first line. Any other reply is feedback: awaywork runs this step again with it.

— awaywork · waits · move=Ready%20for%20design · saw=Inbox
  • It holds its rule. Later runs skip the card as waiting for your approval (approve, story's result), whatever changes, and no rule below takes it. Linked items rank on their own, so a red-CI fix on the linked PR still runs.
  • You answer as on a plan, awaywork approve <source:key> and a included. Feedback reruns the step with the thread in item.md, its new post waiting whatever wait says.
  • Approved, it hands the item on. approved becomes the post's skill, read off the thread, so where: { approved: story } works even where awaywork can't move cards; a newer waiting post leaves it on the one before. The posting rule is done with the item; with no rule after it, the item is skipped as #1 story doesn't run again: you approved its result; to run it again, delete that post on <url> (then awaywork run --unit <key> if the card hasn't changed).
  • on_done waits too. The post holds its move and records the card's status. The first run that sees your approve (window, soon or manual) makes that move, even if on_done changed since, before planning, with no model run: on_done: moved ENG-2101 to Ready for design, its post approved.
  • Gone ahead. A report rule with gates of its own and no wait goes ahead when they run clear (Gates: none fired (taste) on top, — awaywork · went ahead · gates=taste as the mark), moves the card at once and counts as approved. A gate that fires makes it wait, card on top.

Details:

  • A held move happens only while the card is in the status the post saw (on GitHub, the label not on yet) and no newer awaywork post is on the item. A dry run only says it would; the report lists the move, or why it failed, under Held moves. Moving or reassigning the card yourself releases the post.
  • A report rule that waits, or has gates of its own, needs a source that can write, or a thread: naming one that can't is a config error, and doctor warns about any it may match.
  • wait on a pr, draft_pr, push or pending_review rule is a config error: the PR is the decision. So is wait on a planned rule: a report task's result waits only when a gate of its rule fires, and it sets no approved.

The simplest two-stage queue plans the sprint's tasks as reports and implements those you approve:

yaml
queue:
  - skill: plan
    source: asana
    where: { section: Current sprint }
    deliver: report
    wait: true # your approve hands it on
  - skill: implement
    where: { section: Current sprint, approved: plan }

implement finds the plan as its earlier report. While its draft is open the task waits for review; once merged, move the task out of the section and neither rule takes it again.

Threads ​

Your Jira token is read:jira-work, or your custom source has no write: the card can't take awaywork's posts. thread: github on a rule moves the conversation to a GitHub issue awaywork opens in the card's repo (repo_map, or a custom item's repo), assigned to you, so GitHub pings you:

yaml
queue:
  - skill: story
    source: jira # read-only
    deliver: report
    wait: true
    thread: github # posts and replies on an issue in the card's repo
  - skill: prototype
    source: jira
    where: { approved: story }
    deliver: report
    thread: github
    on_done: { comment: result }

The rule's first post opens it:

CARD-1: Export VAT report

awaywork posts here for [CARD-1](https://tracker.example/CARD-1), Export VAT report: its plans, results and questions. Reply here to answer them; the card still decides whether it's yours.

<!-- awaywork thread item=tracker:CARD-1 -->
  • It's the card's thread now. Its comments follow the card's in item.md and wherever awaywork reads posts, so plans, posts that wait, held moves, pins and questions work there. Every post for the card goes there, other rules' and tasks' too, so keep a card's rules on one thread. A reply counts as a change to the card (awaywork's posts don't).
  • Your reply decides: approve on the issue, or awaywork approve jira:ENG-2101 (or the thread's key, github:acme/api#57). A teammate's approve is context. Skips point at the thread: CARD-1: waiting for your approval of story's result on https://github.com/acme/api/issues/212.
  • The card still decides whether it's yours, every run: reassign it and its thread neither fans out nor takes answers. on_done moves stay on the card: one that can't move holds no move, and a plain post's move reports couldn't move ENG-2101 to "Ready": jira can't write to its items.
  • Its end: once the card's source says it's done, closed or merged, read back a week, the next run comments and closes the issue (closed https://github.com/acme/api/issues/212, CARD-1's thread: the card is closed; a dry run says would close).

Details:

  • Each run lists the open issues you opened in the card's repo and takes the one whose marker names the card. The GitHub source leaves issues with the marker out of its items, or a plan rule would take the thread itself.
  • All tasks merged isn't the end: the card says all tasks done: close or move the card until you do, its thread open with it. Close the thread yourself and the next post opens a new one. A thread whose card leaves your items without reading as done (reassigned, moved to another repo, closed while no run read back that week) stays open: close it yourself.
  • thread: <source> names a custom source with thread: true instead, a Notion database or a folder of Markdown files, which opens and lists threads itself (Thread hosts); that's the one for a Bitbucket config, where thread: github is a config error.
  • A thread goes on the plan's rule, never a planned one: tasks post where their plan did. Thread writes use the gh login awaywork opens PRs with, never the worker's.
  • A host that notifies nobody (a Markdown folder) wants a notify hook, or a plan there waits unseen.