Work kinds

A work kind is the rules for one kind of work, such as an investigation, a review or a change. It says how the agent works, what the work can yield, and where finished work lands. Every flight runs under at most one work kind, and the same work kind governs every flight of that kind.

This page explains what a work kind contributes and how it behaves. Write a work kind gives the steps for writing, checking and applying one.

A work kind is one layer of the envelope

A flight’s rules, its envelope, combine three layers:

the rules for one flight = root + work kind + narrowings

Root is the organisation’s base rules, and decides where work may happen at all. The work kind decides what the work is. Narrowings add approvals a repository requires for itself.

The layers combine by these rules:

Part	How it combines
repositories, environments, models, context.constitution	Root only. A work kind may leave them out or repeat root’s value. Declaring a different value is refused.
The organisation’s tool servers	Root only. A work kind that declares them is refused.
loops, destinations, produces, accepts, brief, hosts, consults	Work kind only. They come from the work kind as written. Root’s loop and destination apply only to a flight that runs under no work kind.
context.scope	The overlap of root’s scope and the work kind’s. If neither contains the other, the combination is refused.
obligations	Added together from every layer. Two layers may not declare an obligation with the same name.
instructions	Added together, root’s first, then the work kind’s.
learned	Added together from root and the work kind.

gg envelope show <work-kind> prints root combined with a work kind, with each rule marked by the document it came from.

What a work kind says

What the work may be about: accepts

accepts says what a flight of this kind may concern. Every work kind must declare it, and only a work kind may.

Value	Meaning
repository	A tree to work in.
tracker	A backlog to read, with no tree.
envelope	An airspace document.

An empty list means the work has no subject at all.

accepts decides two other things:

• Which scope is allowed. A work kind that accepts repository declares a path pattern as its context.scope. A work kind that does not must declare scope: none, because there is no tree to change.
• Which facts the work can yield. Facts that need a tree, such as the list of changed files (change.manifest), can only be produced by a work kind that accepts repository. Obligations that read a fact the work kind can never produce are marked not attached, instead of halting the flight.

Removing a value from accepts loosens the rules, and waits for approval.

accepts is read when a person proposes a plan: a leg whose work kind works in a repository must name one. It is not checked against the repositories named by gg fly, so a flight opened directly can name a repository for a work kind that does not accept one, as long as root allows the repository.

What the work yields: produces

produces lists the facts this kind of work can yield, such as change.manifest, loop.outcome or landing.proposal. Every work kind must declare it, even as an empty list. A fact that needs a tree cannot be listed by a work kind that does not accept repository.

The list is a permission, not a promise. An obligation that depends on a fact the list leaves out never applies. For that reason, removing a fact from the list loosens the rules. The envelope: produces explains the effect in detail.

How the work is done: one loop

A work kind has exactly one loop: one agent session, with its executor, model, moves, budget and what happens when the budget runs out. An envelope with a second loop is refused. The envelope: loops describes each setting.

Where the work goes: one destination

A work kind has exactly one destination, which says where finished work lands and which obligations it requires. An envelope with a second destination is refused, and so is one with none, except for an abstract work kind (see below). The envelope: destinations describes each kind of destination.

A work kind must also declare at least one obligation.

What the agent is told: brief, instructions and learned

Three fields reach the agent, each in a different role.

Field	What it is	Who writes it
brief	The job, in one sentence. The agent’s task opens with it.	A person, in the work kind. Only a work kind may set it.
instructions	Standing guidance about how the work is done, passed word for word.	A person, in root and in the work kind.
learned	Advice about what a particular place is like: a repository, a commit, an image or an environment.	Usually an agent, in a flight that rehearses the work and hands the advice back for a person to approve.

brief comes first in the agent’s task: the agent is told what to work on, followed by the brief. A work kind with no brief tells the agent to make the code changes the work asks for. The brief is the place to say “change nothing” or “write a plan, not code”.

instructions follow, introduced as the operator’s standing instructions. Root’s come first, then the work kind’s, and each line is marked with the document it came from.

learned comes later, fenced as reviewed advice that grants nothing. Each entry names what it was learned against, such as a repository and the commit it was true of, so that advice can be told to have gone stale. A flight receives only the entries that match its repository, image or environment. Advice is normally added by a flight whose destination proposes a change to the work kind’s document, which a person approves like any other loosening change. It can also be written by hand. Any addition to learned loosens the rules and waits for approval.

# An example of the three fields together.
brief: "Review the pull request this flight names. Change nothing: the result is the review."
instructions:
  - "Name only paths that were opened and read."
learned:
  - against:
      repository: "example-org/web-app"
      commit: "3a6de3c5cbe45e6bd23e6579d54c30db053a03f3"
    advice:
      - "The test suite needs the database container running; start it before running tests."

Other fields

• description: one line for people choosing a work kind, such as in the console. It governs nothing, and no agent sees it.
• hosts: the environment the work’s running application needs, when that differs from where the agent runs. The control plane checks it against the organisation’s charted environments.
• variables: environment variables for what the flight runs, as names and literal values. They are never secrets. Names use only letters, digits and _, and do not start with a digit.
• consults: the other work kinds whose findings a flight of this kind is handed. Investigations and findings explains it.

Extending another work kind

A work kind can extend another and state only what it changes. The parent is named with extends:, and everything the child leaves out is inherited:

# work-kinds/investigate-instructions.yaml (an example)
extends: investigate
description: "Investigate a work item and write the implementation steps into it."
remove:
  destinations:
    - none
instructions:
  - "End the analysis with a numbered list of implementation steps."
destinations:
  instructions-field:
    kind: work-item-tracker
    requires:
      - investigate-finished
      - investigate-in-scope
    may-perform:
      - field
    may-write:
      - Custom.Instructions

The control plane resolves the chain first, applying each child over its parent, and then combines the result with root and narrowings as usual. The resolved work kind must be valid on its own.

How a child changes what it inherits

What	Rule
Single values and lists, such as description, brief, hosts, accepts, produces and consults	The child’s value replaces the parent’s whole. No list is merged item by item.
Loops, destinations and obligations	Matched by name. A child entry replaces the parent’s entry of the same name whole; a new name is added.
instructions	The child’s are added after the parent’s.
remove:	Takes away the parent’s loops, destinations or obligations by name, and instructions by their exact text.

A removal that matches nothing is refused, naming it, so a parent reworded under its child fails at the child’s next apply instead of being silently kept. Removing an obligation or a destination loosens the rules and is approved like any other loosening change.

In the example, the child removes its parent’s none destination before adding its own, because a work kind has one destination.

What a child cannot do

• Set root’s fields or its own scope. A child cannot set context, environments, repositories, models or the organisation’s tool servers. It inherits its parent’s.
• Set learned or variables. Both belong to complete documents.
• Form a long chain. A chain holds at most three work kinds, counting the top one. The top of the chain must be a complete work kind.
• Change its parent. A child’s name is declared under its parent, and the parent cannot be changed once the name is declared. To move a child, retire it and declare it again.

Abstract work kinds

A work kind that exists only to be extended is marked abstract: true. An abstract work kind:

• is never flown itself. A flight that names it is refused, and the message lists the work kinds that extend it;
• may leave out its destination, but may not declare more than one;
• is checked through each work kind that extends it.

Being abstract is not inherited: a child of an abstract work kind can be flown unless it is marked abstract too.

A family of work kinds

A flight belongs to the family of every work kind in its chain. A flight of investigate-instructions in the example is also an investigate flight. Families decide which earlier findings a flight is handed; see Investigations and findings.

How a flight’s work kind is chosen

Every flight is opened with at most one work kind, and keeps it:

• gg fly --work-kind <name> names it. The name must be a work kind the organisation has declared; an unknown name, a name declared for something else, or an abstract work kind is refused, and nothing is opened.
• With no work kind named, the flight runs under the organisation’s implement work kind. When the organisation has no implement work kind in force, the flight runs under root alone, and root’s loop and destination govern it.
• A nomination names the work kind it would open. It must be on the opens list of the destination it stands under, or it is refused. This covers the legs of a plan, the flights a watch proposes, and the flights an agent proposes. See Nominations and the board.
• In the console, starting a new flight offers the declared work kinds with their descriptions. Its first row sends no work kind, so the flight runs under implement as described above.

The work kind cannot be changed after the flight opens. A flight records every layer of its chain and the version of each that was in force, so a later change to a work kind does not change the rules of a flight already open.

Related

• Write a work kind: writing, checking, applying and extending a work kind.
• The envelope: every field in full.
• Change the airspace: declaring names and applying documents.