gemba-cli 0.1.0__py3-none-any.whl

gemba/assets/skills/gemba-init/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gemba-init
+description: Configure gemba for the first time in a tasks repo that gemba init just created, through a guided interview, one question at a time. Use whenever the user asks to configure gemba, set up gemba, do the first configuration, or customize this tasks repo for their work, right after gemba init.
+---
+
+# Configure a new tasks repo
+
+`gemba init` writes a tasks repo that every command accepts, with a minimal
+`gemba.yaml`: one workstream, `default`, and every agent provider the CLI knows. This
+skill turns that scaffold into the config of the person's own work, once, by asking
+what only they know. Your part is to ask one question at a time, propose the values
+from the answers, and hand the edit over to the `gemba-config` skill, which holds the
+reference of every key and the process to edit, check and refresh.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command.
+
+Run `gemba config show`. This skill is for a tasks repo whose config still holds the
+`default` workstream of the scaffold. When the command finds no config, tell the user
+to run `gemba init` first. When the config holds no `default` workstream, it has been
+configured already: follow the `gemba-config` skill instead.
+
+## Process
+
+Ask the questions below in this order, one per message, and skip any the user already
+answered. Propose a value from each answer and let the user confirm or change it; never
+fill a value the user did not give or confirm.
+
+1. **The organization.** Ask for the name of the organization the work is done for or
+   in. Propose `organization` from it: kebab-case, lowercase letters, digits and single
+   hyphens. It names the branches of the runs.
+2. **The kinds of work.** Ask what kinds of work the person does. Propose one workstream
+   per kind, each with:
+   - an identifier, kebab-case;
+   - a prefix of uppercase ASCII letters, short and used by no other workstream: the
+     refs of its tasks read `<prefix>-<N>`;
+   - a description that lets an agent tell which work belongs there and which does not,
+     since agents choose the workstream of a new task by it.
+3. **The default workstream.** Ask which workstream takes a task that fits no other.
+   The `default` workstream of the scaffold is replaced by the ones the person named,
+   unless they want a catch-all, which then keeps or renames it with a description of
+   its own.
+4. **What to record per task.** Ask what the person needs to know of every task, such
+   as who it is for, the time it took or whether it was billed. Propose one field per
+   answer, each with a snake_case name, one of the four types (`text`, `number`,
+   `boolean`, `date`), whether it is required, and a description. Propose whether every
+   workstream shares the field or only some hold it.
+5. **The agent providers.** The scaffold declares every known provider in
+   `agent_providers`. Ask which agents the person uses and propose the list trimmed to
+   them.
+6. **The IDE.** Ask for the command that opens a folder in their editor, such as
+   `code -n`; it becomes `ide`, run on every harness at launch.
+7. **The repositories folder.** Only when the work involves code: ask for the folder
+   that holds the repositories the runs check out as worktrees; it becomes `repos_dir`,
+   absolute, starting with `~`, or relative to the tasks repo root.
+
+Do not ask for what has a default or comes from use: `branch_prefix`, and the
+`context` and `rules` of the processes.
+
+Then:
+
+8. **Write the config** by following the `gemba-config` skill from its step 4: edit
+   `gemba.yaml` keeping the comments of the scaffold, run `gemba config check` until it
+   exits 0, and run `gemba skills update` when `agent_providers` changed, telling the
+   user which skills folder is left for them to delete.
+9. **Report** the resulting config: the workstreams with their prefixes, the default,
+   the fields, the providers, the IDE command and the repositories folder. End by
+   naming the edits that come later, through the `gemba-config` skill: `branch_prefix`,
+   the first segment of every branch of a run, `gemba` by default; and the `context`
+   and `rules` of any process, which tell agents what to know and do in a workstream
+   or in all of them. Do not commit: the user reviews and commits the tasks repo.
+
+## Rules
+
+- This interview is the first configuration only. Any later change of the config, a
+  workstream, a field, a provider or a rule, follows the `gemba-config` skill.
+- One question per message, in the order above; never ask for a value the user already
+  gave.

gemba/assets/skills/gemba-list/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: gemba-list
+description: List, find or count tasks in this tasks repo. Use whenever the user asks to list, show, find, count or filter tasks, or asks "what do I have open", "what am I working on" or what happened on a task, whatever the workstream.
+---
+
+# List tasks
+
+Answer questions about the tasks in the tasks repo. The `gemba list` command scans the
+task folders, validates every file and applies the filters. Your part is to turn the
+request into filters, run the command, open task files only when the answer needs
+their body, and present the result.
+
+Every organization-specific value (workstreams, prefixes, metadata fields, rules) lives
+in `gemba.yaml`. Run `gemba config show` on every run and rely on nothing else you know
+or remember about workstreams or fields: it prints the config resolved, with the fields
+and the blocks shared by every workstream already joined to those of each one.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command. Do not run the package's
+Python files directly and do not build the list by reading the task folders yourself.
+
+## Process
+
+1. **Locate the config.** Walk up from the current folder to the nearest `gemba.yaml`.
+   That folder is the tasks repo root. If there is none, stop and tell the user that no
+   gemba config was found.
+2. **Choose the workstreams.** Run `gemba config show` from anywhere inside the tasks
+   repo: it prints the config resolved as one JSON document, or the problem when the
+   config is invalid, which you relay before stopping. When the request names an area
+   of work, compare it with the `description` of every entry of `workstreams` in the
+   document and pass one `--workstream` per entry that covers it. When the request
+   names no area, or you cannot tell which entries cover it, pass no `--workstream`:
+   every workstream is listed. Listing is read-only, so listing too much is cheaper
+   than asking.
+3. **Read the `list` block** of every chosen workstream (of every workstream when you
+   pass none): `processes.list` of its entry in the document. Read its `context` as
+   background and follow every entry of its `rules`, in order, when you run the command
+   and present the result; when two rules contradict, follow the later one. A rule
+   shared by every workstream appears in every entry: follow it once.
+4. **Map the request to filters.** Resolve relative dates against today's date (run
+   `date +%F` if you are not sure of it); a week starts on Monday.
+
+   | The user says | Filters |
+   |---|---|
+   | open, pending, active, "what do I have", "what am I working on" | `--status open --status in-progress --status blocked` |
+   | one or more statuses by name (open, in progress, blocked) | one `--status` per named status |
+   | done, finished, closed | `--status done --include-archived` |
+   | a task ref, `<PREFIX>-<N>` | `--ref <PREFIX>-<N> --include-archived` and no other filter |
+   | created on a day or in a period | `--from` and `--to` (the creation date) |
+   | updated, touched or worked on in a period | `--updated-from` and `--updated-to` |
+   | finished in a period | `--done-from` and `--done-to`, with `--include-archived` |
+   | what could have been worked on on a past day D | `--to D --updated-from D` |
+   | archived tasks, everything, including archived | `--include-archived` |
+   | a value of a metadata field | `--where <field>=<value>` |
+   | a span of a number or date field: at least, at most, between, in a period | `--where-from <field>=<low>`, `--where-to <field>=<high>`, or both |
+
+   - A time word restricts dates only when it qualifies an event (created, updated,
+     finished). "What do I have open today" is the open listing with no date filter.
+   - Archived tasks are left out unless the request asks for them, for finished work or
+     for a task by its ref.
+   - For metadata, compare what the user said with the `name` and `description` of
+     every field under `metadata` in the entries of the document, and use the declared
+     name exactly. The command refuses a key that no workstream declares.
+   - Write every metadata value in the form of the field's declared `type`: a `text`
+     value exactly as it is stored, a `number` as a decimal (`3`, `2.5`, `-1`), a
+     `boolean` as `true` or `false`, a `date` as `YYYY-MM-DD`. `<field>=null` finds the
+     tasks where the field has no value, including those whose workstream declares the
+     field and whose file lacks it.
+   - Bounds apply to `number` and `date` fields only, and include their own value: a
+     period such as a month is `--where-from <field>=<first day>` and
+     `--where-to <field>=<last day>`. A task without a value never matches a bound. Give
+     at most one `--where-from` and one `--where-to` per field.
+   - Repeat an option to give alternatives: two `--status` values list tasks with
+     either status, two `--where` values on the same field list tasks with either
+     value. Different options must all match.
+5. **Run the command** from anywhere inside the tasks repo root, every time, even when you
+   listed the same tasks earlier in the conversation:
+
+   ```bash
+   gemba list [--workstream <id> ...] [--status <status> ...] [--ref <ref>] \
+     [--from YYYY-MM-DD] [--to YYYY-MM-DD] \
+     [--updated-from YYYY-MM-DD] [--updated-to YYYY-MM-DD] \
+     [--done-from YYYY-MM-DD] [--done-to YYYY-MM-DD] \
+     [--include-archived] [--where <field>=<value> ...] \
+     [--where-from <field>=<value> ...] [--where-to <field>=<value> ...]
+   ```
+
+   - The command converts every metadata value by the declared type of its field; it
+     never reads a value as YAML, so text is matched exactly as written. Quote the whole
+     argument for the shell when it contains spaces.
+   - If the command refuses, its message lists every invalid filter at once, with the
+     valid workstreams, the allowed statuses or the declared fields. Fix the call and
+     run it again, asking the user only when the request itself is unclear. If the
+     config is missing or invalid, stop and report the message.
+6. **Read the result.** The command prints one JSON object. `tasks` holds one record per
+   matching task: `path` (relative to the tasks repo root), `workstream`, `archived`,
+   `ref`, `date` (created), `title`, `status`, `updated_at`, `done_at`, `metadata` and
+   `description`. `problems` holds the files that are not valid tasks and the metadata
+   values that are not of the type their field declares, each with its `path` and the
+   `problem`.
+7. **Open a task file only when the answer needs its body**: what happened last, the
+   history of the work, the links, what is left to do. Open it from the record's
+   `path`. Progress is under `## Updates`, one `### YYYY-MM-DD` subsection per day in
+   chronological order, so the last subsection is the latest activity.
+8. **Present the result.** Adapt it to the question: a count gets the number, a
+   question about one task gets a short answer, a request for refs gets the refs and
+   titles. When a full listing is wanted, this layout reads well:
+
+   ```
+   <workstream>
+     <ref>  <title>  <status>  updated <updated_at>
+            <description, when it helps>
+
+   Problems
+     <path>: <problem>
+
+   <N> tasks
+   ```
+
+   The layout is a suggestion, not a contract; nothing depends on it. When no task
+   matches, say so plainly and name the filters you used.
+9. **Relay every problem** the command returned, even when the question was about
+   something else: give each path and its problem. Say that a file that is not a valid
+   task is left out of the listing until it is fixed, and that a task whose value is of
+   another type is still listed but matches no condition on that field until the value
+   is set again with `gemba set`. Never fix a task file yourself.
+
+## Rules
+
+- Read, never write: do not edit, move or create any file, and do not commit.
+- Commands own the frontmatter and the agent owns the body; if a frontmatter value
+  looks wrong, tell the user instead of changing it.
+- When `gemba.yaml` changes, follow the new content. This skill never needs an edit when
+  a workstream, field or rule is added, changed or removed.

gemba/assets/skills/gemba-mark/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: gemba-mark
+description: Mark a task done, blocked, open or in progress. Use whenever the user says a task is finished, completed, closed or done, that it is stuck, waiting or blocked, or asks to mark, finish, close, complete, block, unblock, reopen or resume a task, from the tasks repo or inside its harness, whatever the workstream.
+---
+
+# Mark a task
+
+A task moves between four statuses after its creation: `open`, `in-progress`, `blocked`
+and `done`. The `gemba mark` command is the one writer of that move: it sets `status`,
+writes `done_at` when the task reaches `done` and removes it when the task leaves
+`done`, moves `updated_at` forward, and rewrites nothing but the frontmatter. Your part
+is to find the task, turn the user's words into one status, run the command and relay
+what it prints.
+
+Every organization-specific value (workstreams and their rules) lives in `gemba.yaml`,
+at the tasks repo root. Run `gemba config show` on every run and rely on nothing else
+you know or remember about workstreams: it prints the config resolved, with the blocks
+shared by every workstream already joined to those of each one.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command. Never edit the
+frontmatter of a task by hand.
+
+## Process
+
+From the tasks repo or from inside the harness of the task. Inside a harness, the
+folder that holds `harness.yaml` is the harness root.
+
+1. **Identify the task by its ref**, `<PREFIX>-<N>`. Inside a harness, the task is the
+   one named by `ref` in `harness.yaml`, unless the user names another. From the tasks
+   repo, take the ref the user gives; when they name the task by its title or
+   description instead, find it with the `gemba-list` skill. When two or more tasks
+   fit, ask the user which one before marking anything.
+2. **Choose the status** from the user's words:
+
+   | The user says | Status |
+   |---|---|
+   | finished, completed, closed, done | `done` |
+   | stuck, waiting, blocked | `blocked` |
+   | reopen, or bring back a `done` task, without saying the work resumes now | `open` |
+   | continue, resume, unblock, working on it now | `in-progress` |
+
+   When the words fit none of these rows, or fit two, ask the user which status they
+   mean.
+3. **Offer to record the day first.** Only inside a harness and only when the status is
+   `done`: read today's date with `date +%F`, then read `task.md`. When its
+   `## Updates` section has no `### <today>` subsection and `notes/` holds notes of
+   today (`notes/<today>-*.md`), tell the user the day is not recorded yet and offer to
+   record it with the `gemba-record` skill before marking. If they accept, record the
+   day, then go on. If they decline, go on and mark the task anyway.
+4. **Read the `mark` block** of the task's workstream: run `gemba config show` and
+   take the entry of `workstreams` whose `prefix` is the prefix of the ref; for the task
+   of the harness, `gemba config show --workstream <id>` with the `workstream` of
+   `harness.yaml` prints that entry alone. Read `processes.mark` of that entry: `context`
+   as background, and every entry of `rules` to follow, in order, before running the
+   command; when two rules contradict, follow the later one.
+5. **Run the command:**
+
+   ```bash
+   gemba mark <ref> <status> [--date YYYY-MM-DD]
+   ```
+
+   - Pass `--date` only when the user says the change happened on a past day, such as
+     "I finished it yesterday"; resolve that day against `date +%F`. Without it the
+     change is dated today.
+   - If the command refuses, its message lists every problem at once. Fix the call
+     when the problem is yours (the ref, the status, the date) and run it again. When
+     it says the task is archived, relay the message and stop: whether to move the
+     file out of `archive/` is the user's decision, not yours.
+6. **Relay the result** and stop: the task path, the `status:` line, the `done_at:` line
+   when there is one (the date written, or `removed`) and the `updated_at:` line. When
+   the command says the status was left as it was, say the task already had that
+   status.
+
+## Rules
+
+- Commands own the frontmatter: never write `status`, `done_at` or `updated_at` by
+  hand, in `task.md` or in the task file.
+- Marking writes no update. What was done belongs under `## Updates`, through the
+  `gemba-record` skill; marking never replaces recording.
+- Marking does not touch the harness. A task reopened to `open` moves to `in-progress`
+  by itself the next time its harness is launched; a `done` task cannot be launched
+  until it is marked `open` or `in-progress`.
+- When `gemba.yaml` changes, follow the new content. This skill never needs an edit when
+  a workstream or a rule is added, changed or removed.

gemba/assets/skills/gemba-record/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gemba-record
+description: Record the day's work on the task of this harness, distilled from its notes. Use whenever, inside a harness, the user asks to record, log or backfill what was done on the task today, yesterday or on a given date, or to update the task from the notes, whatever the workstream.
+---
+
+# Record the day
+
+The notes of a harness are the memory of the run; the task file is the durable record,
+with one `### YYYY-MM-DD` subsection per day under `## Updates`. Recording promotes one
+day of the run into the task: you distill the notes of that day into a few bullets in a
+draft, and `gemba record` writes them into the task and moves its `updated_at` in the
+same step. Your part is to decide what the bullets say; the command decides where they
+go.
+
+Every organization-specific value (workstreams and their rules) lives in `gemba.yaml`,
+at the tasks repo root. Run `gemba config show` on every run and rely on nothing else
+you know or remember about workstreams: it prints the config resolved, with the blocks
+shared by every workstream already joined to those of each one.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command. Never edit `task.md`.
+
+## Process
+
+Inside the harness of the task. Paths are relative to the harness root, the folder that
+holds `harness.yaml`.
+
+1. **Choose the date.** Today, unless the user names another day. Read today's date
+   with `date +%F` and resolve "yesterday" or a weekday against it. When several dates
+   are to be recorded, take them oldest first and go through steps 2 to 8 once per
+   date, each with its own draft and its own run.
+2. **Read the task and the notes of the date.** Read `task.md` for what the task is and
+   what is already recorded. Then read every note under `notes/` whose name starts with
+   the date, `notes/<YYYY-MM-DD>-*.md`, in the order of their names, whatever their
+   type. Notes of other dates are context, not content for this date.
+3. **Stop when there is nothing to record.** When no note carries the date and this
+   session did nothing on the task that day, tell the user there is nothing to record
+   for that date and stop: write no draft and run no command. When this session did
+   work that day that no note holds yet, file that note first with the `gemba-harness`
+   skill, so that the notes stay the only source of the update.
+4. **Read the `record` block** of the task's workstream: run
+   `gemba config show --workstream <id>` with the `workstream` of `harness.yaml`, from
+   anywhere inside the harness, and read `processes.record`. Read `context` as
+   background and follow every entry of `rules`, in order, while distilling and
+   drafting; when two rules contradict, follow the later one.
+5. **Distill one to five bullets** of what moved that day: what was found, decided,
+   changed or delivered, what is blocked and on whom. Each bullet must make sense to
+   someone who never opens the harness: name the system, the file, the merge request or
+   the person, never a note or an asset of the harness. Leave out process noise: notes
+   filed, files read, commands that changed nothing, attempts that led nowhere unless
+   their failure is the news. Say nothing the notes do not support.
+6. **Write the draft** at the harness root, `update.md`, with your own tools: bullets
+   only, each starting with `- `, and a bullet that runs over several lines continued
+   by lines indented by two spaces. No heading, no date, no frontmatter, no other text.
+   Never write it under `notes/` or `assets/`.
+7. **Run the command** from the harness root:
+
+   ```bash
+   gemba record update.md [--date YYYY-MM-DD]
+   ```
+
+   - Pass `--date` whenever the date is not today.
+   - The command writes the bullets under `### <date>` in the task, after any bullets
+     already recorded for that date, moves `updated_at` to the date when it is later,
+     deletes `update.md` and commits nothing.
+   - If it refuses, its message lists every problem at once. For a problem with the
+     draft or the date, fix the draft or the call and run it again. For a problem with
+     the `## Updates` section of the task, tell the user what the message says: the
+     task file is theirs to fix, and the draft stays for the retry. Never work around a
+     refusal by editing `task.md`.
+   - If it says the task is recorded but the draft could not be deleted, delete
+     `update.md` yourself and do not run the command again: a second run would write
+     the same bullets twice.
+8. **Relay the result:** the task path and the `updated_at` line the command printed,
+   which says whether the date moved or was left unchanged because the task was
+   already updated later, and the bullets you recorded. The user reviews and commits
+   the change in the tasks repo.
+
+## Rules
+
+- `task.md` is read-only: never edit it, and never write a `### YYYY-MM-DD` heading or a
+  frontmatter value by hand. The command is the only writer of the update.
+- Record only what the notes of the date support; when in doubt, leave it out.
+- One draft and one run per date, oldest date first.
+- When `gemba.yaml` changes, follow the new content. This skill never needs an edit when
+  a workstream or a rule is added, changed or removed.

gemba/assets/skills/gemba-report/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: gemba-report
+description: Report what was done in a period, a day, a week or a month, across every task of this tasks repo, with every count and total taken from gemba report. Use whenever the user asks for the daily report, a standup, an end-of-day, weekly or monthly summary, "what did I do today", "yesterday", "this week" or "in September", or how much of an amount went to each workstream, status or value of a field in a period, whatever the workstream.
+---
+
+# Report a period
+
+The report answers what was done in a period, one day or several consecutive days,
+across every task, and how much of each amount went where. `gemba list` finds the tasks
+alive in the period, each task file records its work under `## Updates`, one
+`### YYYY-MM-DD` subsection per day, and `gemba report` computes every count and every
+sum over a selection of tasks. Your part is to list the candidates, read the
+subsections of the period, take every number from `gemba report`, and compose the
+report without adding anything the files and the commands do not say.
+
+Every organization-specific value (workstreams, prefixes, metadata fields, rules) lives
+in `gemba.yaml`. Run `gemba config show` on every run and rely on nothing else you know
+or remember about workstreams or fields: it prints the config resolved, with the fields
+and the blocks shared by every workstream already joined to those of each one.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command. Do not build the list of
+candidates by reading the task folders yourself, and do not compute a number yourself.
+
+## Process
+
+1. **Locate the config.** Walk up from the current folder to the nearest `gemba.yaml`.
+   That folder is the tasks repo root. If there is none, stop and tell the user that no
+   gemba config was found.
+2. **Choose the period**, from F to T, both included. Today, unless the user names
+   another day or period. Read today's date with `date +%F` and resolve "yesterday", a
+   weekday, "this week", "last week", a month or "this month" against it; a week starts
+   on Monday, and a period never ends after today. A day is F equal to T. Several
+   periods give one report each, oldest first, and steps 3 to 9 run once per period.
+3. **List the candidates** of the period with exactly this command, from anywhere
+   inside the tasks repo:
+
+   ```bash
+   gemba list --to T --updated-from F
+   ```
+
+   It returns the tasks created on or before T and updated on or after F, which are
+   exactly the tasks alive in the period. Add `--include-archived` only when the user
+   asks for archived tasks too, and no other filter: the report covers every
+   workstream. Read only the tasks it returns. If the command refuses, relay its
+   message and stop.
+4. **Read the signals of each candidate.** Open the file at the record's `path` and
+   take:
+   - the bullets of every `### D` subsection under `## Updates` whose date D lies from F
+     to T: the work of the period, day by day;
+   - the record's `date` from F to T: the task was created in the period;
+   - the record's `done_at` from F to T: the task was finished in the period.
+
+   A candidate with none of the three has nothing recorded for the period.
+5. **Read the `report` block** of every workstream that has candidates: run
+   `gemba config show` and read `processes.report` of each of their entries. Read
+   `context` as background and follow every entry of `rules`, in order, when composing
+   the entries of that workstream and when choosing a selection for its numbers; when
+   two rules contradict, follow the later one. A rule shared by every workstream
+   appears in every entry: follow it once.
+6. **Take the numbers from `gemba report`** whenever the report states a count, a sum or
+   a total, and whenever the user asks how much of something went where. The command
+   takes the filters of `gemba list` and prints one JSON object:
+
+   ```bash
+   gemba report --done-from F --done-to T [--by <grouping> ...] [--sum <field> ...]
+   ```
+
+   - **Selection.** A number field holds one total per task, so the totals of a period
+     are those of the tasks finished in it: select with `--done-from F --done-to T`
+     unless the user asks for another selection (created in the period is
+     `--from F --to T`; a date field in the period is `--where-from <field>=F
+     --where-to <field>=T`) or the `report.rules` of the workstreams involved say
+     otherwise. Add `--include-archived` when the user asks for archived tasks too.
+     Narrow it with `--workstream`, `--status` or `--where` when the question does.
+   - **Groupings.** `--by workstream`, `--by status`, or `--by <field>` for a field
+     whose declared `type` is `text` or `boolean`, when the user asks for amounts per
+     workstream, per status or per value of a field. Repeat `--by` to group within
+     groups. Map the user's words to fields by the `name` and `description` of every
+     field under `metadata` in the entries of the document of step 5, and write every
+     value by its field's declared type, as `gemba list` takes them.
+   - **Sums.** `--sum <field>` for a field whose declared `type` is `number`.
+   - **Reading.** `groups` holds one entry per combination of grouping values: `key`
+     (each grouping and its value, `null` for tasks without one), `tasks`, `refs` and,
+     per summed field, `total` and `missing`, the tasks without a number to add.
+     `total` holds the same over every selected task, each counted once. A task whose
+     text field holds a list is counted in the group of each item, so the groups may add
+     up to more than the total: say so when you report both.
+   - If the command refuses, its message lists every invalid filter, grouping and sum at
+     once. Fix the call and run it again, asking the user only when the request itself
+     is unclear.
+
+   State only the numbers the command printed: each total, each count, and the tasks
+   without a value whenever `missing` is not zero. Never add, subtract, average or
+   compare numbers yourself; when the user wants a total the command did not print,
+   such as two groups together, run `gemba report` again with the selection or the
+   grouping that yields it. Say which selection the numbers come from, such as "tasks
+   finished from F to T".
+7. **Compose the report** in the language the user converses in, grouped by
+   workstream unless the user asks for another grouping, with one entry per task that
+   has a signal for the period: its title, ref and current status, then the bullets of
+   the period, condensed rather than transcribed. A task created or finished in the
+   period says so, without bullets made up for it. When no candidate has a signal for
+   the period, say plainly that nothing was recorded for it. This layout reads well:
+
+   ```
+   Report for <F> to <T>
+
+   <workstream>
+     <ref>  <title>  <status>
+       - <condensed bullet>
+       - created on <date> | finished on <done_at>
+
+   Numbers (<the selection used>)
+     <group>  <count> tasks  <field>: <total> (<missing> without a value)
+
+   Updated recently, nothing recorded from <F> to <T>
+     <ref>  <title>  <status>  updated <updated_at>
+   ```
+
+   The layout is guidance, not a contract: adapt it to the question asked; nothing
+   depends on it. A question about amounts alone gets the numbers alone.
+8. **List the gaps at the end:** every candidate with nothing recorded for the period,
+   under a heading saying they were updated recently with nothing recorded for that
+   period, with no bullets, so the user can record what is missing.
+9. **Relay every problem** that `gemba list` or `gemba report` returned, alongside the
+   report: give each path and its problem. A file that is not a valid task is left out
+   until it is fixed; a value that is not of its field's type is grouped under `null`
+   and counted as missing until it is set again with `gemba set`.
+
+## Filling a gap
+
+The report never fills a gap. To record what a task is missing, point the user to the
+harness of that task, `harnesses/<workstream>/<task file name without .md>/`, and the
+`gemba-record` skill used inside it; a task with no harness yet is launched with the
+`gemba-harness` skill. A metadata value that is missing or wrong is set with the
+`gemba-set` skill.
+
+## Rules
+
+- Read, never write: do not edit, move or create any file, and do not commit.
+- State no activity that a subsection of the period, a creation date or a `done_at`
+  does not support, and no number that `gemba report` did not print. A task with
+  nothing recorded is a gap to show, not one to fill from memory.
+- When `gemba.yaml` changes, follow the new content. This skill never needs an edit when
+  a workstream, field or rule is added, changed or removed.

gemba/assets/skills/gemba-set/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: gemba-set
+description: Set, change, correct or clear a metadata value of a task, or add to an amount it holds, such as the time it took, from the tasks repo or inside its harness. Use whenever the user gives a value of a task's field after its creation, says a task took more time or more of any amount than recorded, says something happened to a task on a date a field records, or asks to set, change, fix, clear, log or add to a value of a task, whatever the workstream. Recording the day's work is gemba-record and the status of a task is gemba-mark.
+---
+
+# Set metadata of a task
+
+The metadata of a task is the map of values its workstream declares in `gemba.yaml`,
+each field with a `type`: `text`, `number`, `boolean` or `date`. The `gemba set` command
+is the one writer of those values after creation: it converts every value by the type
+of its field, adds to a number without anyone doing the sum, completes the map with the
+keys of the current schema, and rewrites nothing but `metadata`; `updated_at` does not
+move. Your part is to find the task, turn the user's words into assignments of declared
+fields, run the command once and relay what it prints.
+
+Every organization-specific value (workstreams, prefixes, metadata fields, rules) lives
+in `gemba.yaml`, at the tasks repo root. Run `gemba config show` on every run and rely
+on nothing else you know or remember about workstreams or fields: it prints the config
+resolved, with the fields and the blocks shared by every workstream already joined to
+those of each one.
+
+## Prerequisite
+
+The `gemba` command must be on the PATH. It is installed once from PyPI with
+`uv tool install gemba-cli` and checked with `gemba --version`. If `gemba` is not
+found, stop and tell the user to install it with that command. Never edit the
+frontmatter of a task by hand.
+
+## Process
+
+From the tasks repo or from inside the harness of the task. Inside a harness, the
+folder that holds `harness.yaml` is the harness root.
+
+1. **Identify the task by its ref**, `<PREFIX>-<N>`. Inside a harness, the task is the
+   one named by `ref` in `harness.yaml`, unless the user names another. From the tasks
+   repo, take the ref the user gives; when they name the task by its title or
+   description instead, find it with the `gemba-list` skill. When two or more tasks
+   fit, ask the user which one before setting anything.
+2. **Read the schema of the task.** Its workstream is the one whose `prefix` is the
+   prefix of the ref: run `gemba config show` and take the entry of `workstreams` with
+   that `prefix`; for the task of the harness, `gemba config show --workstream <id>`
+   with the `workstream` of `harness.yaml` prints that entry alone. The `metadata` of
+   that entry lists every field the task may hold, each with its `name`, `type`,
+   `required` and `description`. Read its `processes.set` too: `context` as background,
+   and every entry of `rules` to follow, in order, before running the command; when two
+   rules contradict, follow the later one.
+3. **Map the user's words to declared fields** by their names and descriptions. Use the
+   declared name exactly. When nothing in the schema fits what the user said, tell them
+   which fields are declared and stop: a new field is an edit of `gemba.yaml`, not a
+   value to invent.
+4. **Write each assignment by the field's `type`:**
+
+   | Type | The user says | Assignment |
+   |---|---|---|
+   | `number` | a new total | `<field>=<decimal>`, such as `3` or `2.5` |
+   | `number` | more of an amount, "another", "two more" | `<field>+=<decimal>` |
+   | `boolean` | yes or no | `<field>=true` or `<field>=false` |
+   | `date` | a day | `<field>=YYYY-MM-DD` |
+   | `text` | a value | `<field>=<value>`, exactly as it should read |
+   | `text` | several values | `<field>=<one> <field>=<two>`, the whole list |
+   | any | remove, clear, unset | `<field>=null` |
+
+   - Resolve "today", "yesterday" or a weekday against `date +%F`.
+   - Use `+=` whenever the user adds to an amount instead of stating the new total, and
+     never add, subtract or convert numbers yourself. When the user gives an amount in
+     another unit than the one the field's name or description implies, ask for it in
+     the field's unit.
+   - A text list replaces the whole value: to add one item, give every item.
+   - For a `text` field, look up the values already in use before writing one:
+
+     ```bash
+     gemba report --by <field> --include-archived
+     ```
+
+     The `key` of each group is a value in use. When the user means one of them,
+     written another way (another case, an abbreviation), use the spelling in use; when
+     you cannot tell whether the user means a value in use or a new one, ask.
+5. **Run the command once,** with every assignment, from anywhere inside the tasks repo
+   or the harness:
+
+   ```bash
+   gemba set <ref> <field>=<value> [<field>+=<number> ...]
+   ```
+
+   Quote an assignment for the shell when it contains spaces. If the command refuses,
+   its message lists every problem at once. Fix the call when the problem is yours
+   (a field name, the form of a value) and run it again. When it says a required field
+   would be left null, ask the user for that value and pass it in the same call. When it
+   cannot add to a value that is not a number, tell the user and ask for the total to
+   set with `=`.
+6. **Relay the result** and stop: the task path and one line per field, `old -> new`,
+   `(unchanged)` when the value was already there, or `added as null` for a field the
+   task lacked because it was declared after the task was created.
+
+## Rules
+
+- Commands own the frontmatter: never write `metadata`, or any other frontmatter key,
+  by hand, in `task.md` or in the task file.
+- Setting records no work and moves no status. What was done belongs under
+  `## Updates`, through the `gemba-record` skill; the status belongs to the `gemba-mark`
+  skill.
+- Choose the assignment by the declared `type` of a field, never by its name.
+- When `gemba.yaml` changes, follow the new content. This skill never needs an edit when
+  a workstream, field or rule is added, changed or removed.