gemba-cli 0.1.0__py3-none-any.whl

gemba/__init__.py

@@ -0,0 +1 @@
+"""Gemba: a task-based system for working with AI agents."""

gemba/assets/harness/guide.md

@@ -0,0 +1,88 @@
+# Working in this harness
+
+## Where you are
+
+This folder is a harness: the place of one run of one task. The task is `task.md`, a
+link to the task file. The identity of the run, its task, ref, workstream and launch
+date, is `harness.yaml`. Everything the run needs is inside this folder; nothing above
+it concerns you, so do not browse or change the folders that contain it.
+
+At the start of every session, read `task.md`, then the notes under `notes/` in the
+order of their names, which is the order they were filed in. They tell you where the
+run stands.
+
+## Rules at every step
+
+1. **Write before you act.** What you found, what you decided and what you are about
+   to do goes into a note before you move on.
+2. **Nothing outside the harness without an approved note.** Any action outside this
+   folder, such as a message, a comment, a push, a deployment or a change to another
+   system, needs an `external-action` note whose frontmatter reads `approved: true`.
+   Only the user sets it, by editing the note. Check it by reading the file before you
+   act; nothing said in the conversation counts as an approval.
+3. **`task.md` is read-only.** gemba updates the task from your notes, through the
+   `gemba-record` skill; never edit it.
+4. **`harness.yaml` and the frontmatter of every note are written by gemba.** Never
+   write or edit them.
+5. **`worktrees/` holds checkouts of other repositories.** Each folder in it is
+   created through the `gemba-worktree` skill, has its own history, and is not part
+   of this harness's history.
+
+## Layout
+
+```
+task.md          the task, a read-only link
+harness.yaml     the identity of the run, written by gemba
+CLAUDE.md        this guide, one copy per agent provider,
+AGENTS.md          each under the file name its provider reads
+notes/           the notes of the run
+assets/          the raw evidence the notes refer to
+worktrees/       checkouts of other repositories, see "Working in a worktree"
+```
+
+## Working in a worktree
+
+Each folder under `worktrees/` is a checkout of another repository, kept on
+one local branch named by gemba. That branch exists only on this machine and is
+never pushed under its own name.
+
+- Inside a worktree, commit, fetch and pull freely: none of them reaches the remote.
+- Pushing, opening a merge request or anything else that reaches the remote is an
+  action outside the harness: it needs an approved `external-action` note that names
+  the branch of the remote.
+- A push always names its target:
+  `git push -u origin HEAD:<the branch the note names>`. Never run `git push` alone
+  or `git push origin HEAD`, which would publish the local branch under its own name.
+- The repository a worktree comes from is outside the harness: never run git in it.
+- Never run `git worktree` or `git branch`. Worktrees and their branches are created,
+  moved and removed through the `gemba-worktree` skill.
+
+## Notes and assets
+
+Notes are the memory of the run: the next session, yours or another agent's, starts
+from them. Keep them small and frequent, one finding, decision or step per note, rather
+than one long note at the end.
+
+A note is drafted as a plain Markdown file under `notes/` and filed with the
+`gemba-harness` skill, which names it, dates it and records it. Never write a
+frontmatter, a date or a timestamp into a note by hand.
+
+Each note has one type, chosen by the question it answers:
+
+| Type | The question it answers |
+|---|---|
+| `finding` | What is true, and what is the evidence for it? |
+| `blocker` | Why can the run not continue, what was tried, and what is needed? |
+| `decision` | What are the options, their trade-offs, and the recommendation or the choice? |
+| `summary` | Where does the run stand at this milestone, and what remains? |
+| `external-action` | What exactly is to be done outside the harness, word for word? |
+
+Assets are the raw evidence: logs, screenshots, exports, responses. Save each one under
+`assets/`, named `<unix-timestamp>-<slug>.<ext>` with the timestamp taken from the
+system clock, and reference it from the note that explains it.
+
+## Commits
+
+This folder is its own git repository. gemba commits when the harness is launched and
+when a note is filed or resolved, so a filed note and its assets are never left
+uncommitted. Do not commit here yourself.

gemba/assets/init/gemba.yaml

@@ -0,0 +1,12 @@
+# The gemba config of this tasks repo, edited by hand: no gemba command rewrites it.
+# Ask your agent to configure gemba for the first time (the gemba-init skill) and to
+# change it later (the gemba-config skill, which holds the reference of every key).
+
+default_workstream: default
+
+agent_providers: __PROVIDERS__
+
+workstreams:
+  default:
+    prefix: TASK
+    description: Work that fits no other workstream

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

@@ -0,0 +1,78 @@
+---
+name: gemba-archive
+description: Archive tasks of this tasks repo that went cold, so that they leave the listings. Use whenever the user asks to archive tasks, to put away cold, old or inactive tasks, or to clean up the task list, whatever the workstream.
+---
+
+# Archive tasks
+
+A task that went cold moves, unchanged, into the `archive/` folder of its workstream:
+it leaves the listings and stays findable on request. The `gemba archive` command moves
+the files, one or many in one call, whatever their status, and refuses the ones it
+cannot move. Your part is to find the tasks with the user, get their confirmation, run
+the command once and relay every line 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 move a task file
+yourself, with `mv`, `git mv` or any other tool.
+
+## Process
+
+From anywhere inside the tasks repo.
+
+1. **Take the refs the user names.** When the user names the tasks by ref, go to
+   step 4 with those refs. When they name them by title or description, find their
+   refs with the `gemba-list` skill.
+2. **Find the candidates** when the user asks to archive what went cold. Settle the
+   date first: tasks not updated since that date are cold. Use the date the user
+   names; when they name none, propose one, such as a month before today (read today
+   with `date +%F`), and wait for them to confirm or change it. Then run:
+
+   ```bash
+   gemba list --updated-to <date> --status done
+   ```
+
+   Pass one `--status` per status the user names instead of `done` when they want
+   other statuses archived too, such as blocked tasks nobody came back to.
+3. **Show the candidates and confirm.** Show them as a short table, one row per task
+   with its ref, title, status and last update, and ask the user which to archive. Let
+   them confirm all, drop some or stop. When there are none, say so with the date and
+   statuses you used, and stop.
+4. **Read the `archive` block** of every workstream involved: run `gemba config show`
+   and read `processes.archive` of each of their entries. Read `context` as background
+   and follow every entry of `rules`, in order, before proposing and before running the
+   command; when two rules contradict, follow the later one, and follow a rule shared by
+   every workstream once. When a rule excludes a task, tell the user why and leave it
+   out.
+5. **Run the command once** with every confirmed ref:
+
+   ```bash
+   gemba archive <ref> [<ref> ...]
+   ```
+
+   Each ref is handled on its own: the command prints `archived: <new path>` for each
+   task it moved and `not archived: <ref> <reason>` for each one it refused, and exits
+   1 when it refused any.
+6. **Relay every line.** Give the paths that were archived and every `not archived:`
+   line with its reason. When a task was refused because its harness still exists, say
+   that `gemba harness remove <ref>` clears it, through the `gemba-harness` skill, and
+   that the task can be archived once its harness is gone. The user reviews and
+   commits the moves in the tasks repo.
+
+## Rules
+
+- The command is the only way a task file moves into `archive/`. Never move, rename or
+  edit a task file yourself.
+- Archiving changes no byte of the task: its status and `updated_at` stay as they were.
+- An archived task is left out of `gemba list` unless `--include-archived` is given.
+  Bringing one back out of `archive/` is the user's own move, made by hand; tell them
+  so when they ask, and do not do it for them.
+- 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-config/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: gemba-config
+description: Explain, check, show and edit gemba.yaml, the config of this tasks repo. Use whenever the user asks to add, change or remove a workstream, a field, a provider, the IDE command, the repositories folder or the context and rules of a process, or asks what the config can hold.
+---
+
+# Maintain the gemba config
+
+`gemba.yaml`, at the root of the tasks repo, is the customization of the organization:
+its workstreams, the fields a task records, the agent providers, and the context and
+rules of every process. Every command reads it; no command writes it after `gemba init`
+created it. Every change is an edit of the file by hand, by the user or by you on their
+behalf. `gemba config check` validates the file and `gemba config show` prints it
+resolved. Your part is to know what the file can hold, to edit it keeping everything
+else as it was, and to prove the edit valid with `gemba config check`.
+
+## 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.
+
+## Reference
+
+Every example below is only an example: the names of this tasks repo are in its own
+`gemba.yaml`, which `gemba config show` prints.
+
+### Top level
+
+| Key | Holds | When absent |
+|---|---|---|
+| `default_workstream` | the identifier of a workstream of the catalogue, where a task goes when no description covers it | refused: it is required |
+| `workstreams` | a non-empty map of workstreams, keyed by identifier; its order is the order reports group by | refused: it is required |
+| `metadata` | the list of field declarations shared by every workstream | no shared field |
+| `agent_providers` | a non-empty list of the agent providers whose skills folders gemba writes, each listed once: `claude` (`.claude/skills/`, guide `CLAUDE.md`) or `agents` (`.agents/skills/`, guide `AGENTS.md`) | `gemba skills update`, `gemba harness launch` and `gemba init` refuse to run |
+| `ide` | a non-empty string, the command that opens a folder in the IDE, arguments included, such as `code -n`; launch appends the harness path | launch opens nothing |
+| `organization` | a kebab-case name, the middle segment of the branch of a run, `<branch_prefix>/<organization>/<ref>` | `gemba worktree add` refuses to run |
+| `repos_dir` | the folder of the repositories a run may check out as worktrees: absolute, starting with `~`, or relative to the tasks repo root | `gemba worktree add` refuses to run |
+| `branch_prefix` | a kebab-case name, the first segment of the branch of a run | `gemba` |
+
+The top level may also hold the process blocks described below, `create`, `list`,
+`record`, `report`, `mark`, `archive`, `set`, `harness` and `worktree`: the base
+blocks, shared by every workstream. No other process key is read.
+
+### A workstream
+
+```yaml
+workstreams:
+  support:
+    prefix: SUP
+    description: Investigate a client-reported problem
+    metadata:
+      - name: client
+        type: text
+        required: true
+```
+
+- The identifier, the key of the entry, is kebab-case (lowercase letters, digits and
+  single hyphens). It names the folder of its tasks, `tasks/<identifier>/`.
+- `prefix` is required: one or more uppercase ASCII letters, used by no other
+  workstream. Refs are `<prefix>-<N>`. Quote it, as in `prefix: "ON"`, when YAML would
+  read it as a boolean.
+- `description` is required and not empty. Agents choose the workstream of a new task
+  by it, so it says which work belongs there and which does not.
+- `metadata` lists the fields of this workstream.
+- Any process block, with the same shape as at the top level.
+
+### A field
+
+```yaml
+metadata:
+  - name: client
+    type: text
+    description: Client the work is done for
+```
+
+- `name` is required: snake_case (lowercase letters, digits and single underscores),
+  declared once per list. `workstream` and `status` are reserved: every report groups
+  tasks by them.
+- `type` is required, one of four, and tells every process how to read and operate on
+  a value, never what it means: `text` (the one type that may hold a list), `number`
+  (a decimal), `boolean` (`true` or `false`) or `date` (`YYYY-MM-DD`). A name keeps one
+  type across the whole file, in every list that declares it.
+- `required` is `true` or `false`, `false` when absent: `gemba create` refuses a task
+  without a value for a required field.
+- `description` is optional and not empty: agents map the user's words to the field
+  by its name and description, and ask for a required value with it.
+- A declaration takes no other key.
+
+The fields of a workstream are the shared ones and its own, joined by name: a field the
+workstream declares with the name of a shared one replaces that declaration entirely.
+
+### Process blocks
+
+```yaml
+create:
+  context: Every task is billed to one client.
+  rules:
+    - ask who requested the work if not stated
+worktree:
+  add:
+    rules:
+      - start from the default branch of origin
+```
+
+- A block holds `context`, a string the agent reads as background, and `rules`, a list
+  of non-empty strings the agent follows. Both are optional.
+- `create`, `list`, `record`, `report`, `mark`, `archive` and `set` are one verb each:
+  the block sits directly under the process name.
+- `harness` and `worktree` are groups: the block sits under each verb, `harness.launch`,
+  `harness.note`, `harness.resolve`, `harness.remove`, `worktree.add`, `worktree.list`
+  and `worktree.remove`. A group takes no other key, except `harness.guide`.
+- `harness.guide` is a non-empty string written into the guide of every harness
+  launched afterwards: the top-level text under `## Your organization` and the
+  workstream's under `## Your workstream`. A harness already launched keeps its guide.
+- The block that applies to a workstream joins the top level and the workstream: the
+  top-level context then the workstream's, every top-level rule then every rule of the workstream, the rule of
+  the workstream winning a contradiction. `gemba config show` prints it joined, under
+  `processes` of each workstream.
+
+## Process
+
+1. **Locate the config.** Walk up from the current folder to the first folder that holds
+   `gemba.yaml`: it is the tasks repo root. If there is none, stop and tell the user
+   that a tasks repo is started with `gemba init` and configured the first time through
+   the `gemba-init` skill.
+2. **Read the current state** with `gemba config show`, and read `gemba.yaml` itself,
+   since the edit is made there. When the command refuses, the file is already invalid:
+   tell the user and go to step 5 with the problem it names.
+3. **Ask for what the edit needs and the user did not say**, one question at a time,
+   proposing a value from what they said: for a workstream, its identifier, prefix and
+   description; for a field, its name, type, whether it is required, its description,
+   and whether every workstream shares it or one workstream holds it; for a rule or a
+   context, the process or verb and whether it is shared or belongs to one workstream.
+   Check each value against the reference and the current state: an identifier or a
+   prefix already in use, or a field name declared with another type, is refused. Do
+   not ask for what the user did not raise and has a default, such as `branch_prefix`.
+4. **Edit `gemba.yaml`** with your own tools, changing only what the edit needs: keep
+   every other line, comment, key and their order as they were, and write new keys in
+   the style of the file. Never rewrite the file from the output of `gemba config show`:
+   it holds defaults and joined blocks that the file does not.
+5. **Check the file:**
+
+   ```bash
+   gemba config check
+   ```
+
+   It exits 0 with a summary when the config is valid; otherwise it exits 1 naming the
+   file and the first problem. Fix that problem and run it again until it exits 0: it
+   reports one problem at a time. Never leave an invalid config behind, since every
+   command refuses to run while it is.
+6. **Refresh the skills when `agent_providers` changed**, from the tasks repo root:
+
+   ```bash
+   gemba skills update
+   ```
+
+   It writes the skills of a provider added. A provider removed keeps its skills
+   folder: tell the user that `.claude/skills/` or `.agents/skills/` is left for them to
+   delete. A harness keeps the providers it was launched with.
+7. **Report** what changed in the file, the summary `gemba config check` printed and
+   what follows from the edit: the skills written, a folder left to delete, tasks whose
+   values no longer match a field. Do not commit: the user reviews and commits the
+   tasks repo.
+
+## Rules
+
+- The CLI never writes `gemba.yaml`. Edit it by hand, and run `gemba config check`
+  after every edit.
+- Never move, rename or edit a task file because the config changed. A workstream
+  renamed or removed leaves its folder under `tasks/` as it is, and `gemba list`
+  reports that folder as a problem until the user moves it; a prefix changed leaves
+  every ref already allocated as it is; a field changed leaves every value already
+  written as it is, and a value no longer of its field's type is reported until
+  `gemba set` writes it again. Tell the user so.
+- No organization's names belong in a skill or in the CLI: every workstream, field and
+  rule of the tasks repo lives in its `gemba.yaml`.

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

@@ -0,0 +1,99 @@
+---
+name: gemba-create
+description: Register a new task in this tasks repo. Use whenever the user asks to register, create, track or add a task, TODO or work item, whatever the workstream.
+---
+
+# Create a task
+
+Register one unit of work as a task file. The `gemba create` command validates the
+request, allocates the ref and writes the file. Your part is to choose the workstream,
+gather what the config requires, run the command and complete the body.
+
+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 write the task file by hand.
+
+## 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 workstream.** 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. Compare the request with the
+   `description` of every entry of `workstreams` in the document:
+   - one description clearly covers the work: use that workstream without asking;
+   - no description covers it: use `default_workstream`;
+   - two or more cover it equally well: ask the user which one before creating anything.
+3. **Read the fields of the chosen workstream.** The `metadata` of its entry lists every
+   field the task may hold, each with its `name`, `type`, `required` and `description`.
+4. **Read the `create` block** of the chosen workstream, `processes.create` of its entry.
+   Read its `context` as background and follow every entry of its `rules` in order,
+   including any question a rule tells you to ask; when two rules contradict, follow
+   the later one.
+5. **Gather required fields.** For every field with `required: true` whose value the user
+   has not given, ask for it, phrasing the question with the field's `description` when
+   it has one. Ask for all of them in one message. Never ask for optional fields; pass
+   an optional field only when the user mentioned its value.
+6. **Write each value by its type.** Every field declares a `type`, and the command
+   converts the value by it:
+   - `text`: the value exactly as it should read; a field of this type alone holds a
+     list, given by repeating the key;
+   - `number`: a decimal such as `3`, `2.5` or `-1`;
+   - `boolean`: `true` or `false`;
+   - `date`: `YYYY-MM-DD`.
+
+   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), pass it with the spelling in use; when
+   you cannot tell whether the user means a value in use or a new one, ask.
+7. **Build the slug** from what the user said. It is the task's title: a few lowercase
+   ASCII words or numbers joined by single hyphens, matching `^[a-z0-9]+(-[a-z0-9]+)*$`.
+   Transliterate accented letters and drop punctuation.
+8. **Run the command** from anywhere inside the tasks repo root:
+
+   ```bash
+   gemba create --workstream <id> --slug <slug> \
+     [--date YYYY-MM-DD] [--status in-progress|blocked] \
+     [--description "<short description>"] [--set <key>=<value> ...]
+   ```
+
+   - Pass `--date` only when the user states a creation date other than today.
+   - Pass `--status` only when the user says the work is already in progress or blocked.
+     New tasks are `open` by default and `done` is refused.
+   - Pass `--set` once per value, written as step 6 says; repeat the key of a `text`
+     field to give a list. Values are never read as YAML: text is kept exactly as
+     written. Quote the argument for the shell when it contains spaces.
+   - Never choose a ref: the command allocates it. An external identifier such as a
+     ticket key or a link goes into a declared metadata field or into the body, never
+     into the slug.
+
+   If the command refuses, its message lists every problem at once, including every
+   missing and every undeclared key and every value that is not of its field's type. Fix the call, asking the user when a value is
+   missing, and run it again. Never work around a refusal by writing or editing the
+   file yourself.
+9. **Complete the body.** The command prints the created path, relative to the tasks
+   repo root, and the ref. If you did not pass `--description`, write a short description
+   above `## Updates` now. Add links to any external references the user gave below
+   the description. Edit only the body and leave `## Updates` empty.
+10. **Report** the path, the ref and a one-line summary to the user. Do not commit.
+
+## Rules
+
+- Commands own the frontmatter, including `metadata`; you own the body. Never edit the
+  frontmatter by hand, not even to fix a value; tell the user what is wrong instead.
+- 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-harness/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: gemba-harness
+description: Launch, start or open the harness of a task, file notes inside one, and remove one. Use whenever the user asks to launch, start, open or work on a task in its own harness, to remove, delete, throw away or clean up the harness of a task, or, inside a harness, to note, file or log a finding, a blocker, a decision, a summary or an action to take outside it, or to act on a note the user approved, whatever the workstream.
+---
+
+# Work in a harness
+
+A harness is the folder of one run of one task: its own git repository and the root the
+IDE opens. The `gemba harness` commands create it, file its notes, record what was
+done on an approved note and remove it. Your part is to write the notes, choose their
+type, run the commands with the right arguments and relay what they print.
+
+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, from the tasks
+repo or from inside a harness: the entry of each workstream holds, under `processes`,
+the block of every verb that applies to it, such as `processes.harness.note`, with the
+block shared by every workstream already joined to the workstream's. Wherever this
+skill says to read a block, read its `context` as background and follow every entry of
+its `rules` in order; when two rules contradict, follow the later 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 create, rename or
+commit a file of the harness by hand, and never write a frontmatter.
+
+## Launch
+
+From anywhere inside the tasks repo:
+
+1. **Identify the task by its ref**, `<PREFIX>-<N>`. When the request names 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 launching anything.
+2. **Read the `harness.launch` block:** run `gemba config show` and read
+   `processes.harness.launch` in the entry of `workstreams` whose `prefix` is the prefix
+   of the ref. Read `context` as background and follow every entry of `rules`.
+3. **Run the command:**
+
+   ```bash
+   gemba harness launch <ref>
+   ```
+
+   Pass `--no-open` only when the user says not to open the IDE. If the command
+   refuses, relay its message; never work around it.
+4. **Relay the result** and stop: the harness path it printed, the status line (the
+   task moved to `in-progress`, or left as it was), and whether the IDE was opened (an
+   `opening:` line) or not. When it says the harness is already launched, say so. The
+   work itself happens in a session started inside the harness.
+
+## Note
+
+Inside a harness, every time there is something to record. Paths are relative to the
+harness root, the folder that holds `harness.yaml`.
+
+1. **Draft the note** as a plain Markdown file directly under `notes/`, with your own
+   tools, named `<slug>.md`: a few lowercase ASCII words or numbers joined by single
+   hyphens, such as `notes/login-trace.md`. Write the body only: no frontmatter, no date,
+   no timestamp. Keep it to one finding, decision or step; an `external-action` note
+   says word for word what is to be done, where and with which values.
+2. **Save the evidence first.** Each asset goes under `assets/`, named
+   `<unix-timestamp>-<slug>.<ext>`. Read the timestamp from the system clock with
+   `date "+%s %F"`, whose first value is the timestamp; never make one up. Mention each
+   asset in the body of the note that explains it.
+3. **Choose the type** by the question the note answers:
+
+   | Type | The question it answers |
+   |---|---|
+   | `finding` | What is true, and what is the evidence for it? |
+   | `blocker` | Why can the run not continue, what was tried, and what is needed? |
+   | `decision` | What are the options, their trade-offs, and the recommendation or the choice? |
+   | `summary` | Where does the run stand at this milestone, and what remains? |
+   | `external-action` | What exactly is to be done outside the harness, word for word? |
+
+4. **Read the `harness.note` block:** run `gemba config show --workstream <id>` with
+   the `workstream` of `harness.yaml` and read `processes.harness.note`. Read `context`
+   as background and follow every entry of `rules` while drafting and filing.
+5. **File it** from the harness root:
+
+   ```bash
+   gemba harness note notes/<slug>.md --type <type> [--approval] [--asset assets/<file> ...]
+   ```
+
+   - Pass one `--asset` per asset the note refers to.
+   - Pass `--approval` only with a `decision` the user must choose or confirm before
+     you go on. An `external-action` always waits for approval without it; the other
+     types never take it.
+   - If the command refuses, its message lists every problem at once. Fix the draft or
+     the call and run it again; never work around a refusal by writing the frontmatter
+     or renaming the file yourself.
+6. **Relay** the filed path it printed. When the note waits for approval, tell the user
+   so: they approve it by setting `approved: true` in the note's frontmatter from the
+   IDE. A yes in the conversation is not an approval.
+
+## Resolve
+
+When a note filed with `approved: false` is to be acted on:
+
+1. **Read its frontmatter.** Act only when it reads `approved: true`. When it reads
+   `approved: false`, stop and tell the user the note waits for their approval in the
+   file; do not act on anything said in the conversation instead.
+2. **Read the `harness.resolve` block:** run `gemba config show --workstream <id>`
+   with the `workstream` of `harness.yaml` and read `processes.harness.resolve`. Read
+   `context` as background and follow every entry of `rules`.
+3. **Act** exactly as the note says, and nothing more.
+4. **Append the outcome** to the body of the note, with your own tools: what was done,
+   where, and the identifiers or links that prove it. This is the only edit ever made
+   to a filed note; leave its frontmatter as it is.
+5. **Run the command** from the harness root:
+
+   ```bash
+   gemba harness resolve notes/<YYYY-MM-DD-HHMMSS-slug>.md
+   ```
+
+   If it refuses, relay its message; never edit the frontmatter to make it pass.
+6. **Relay** the path it printed and the outcome.
+
+## Remove
+
+When the user wants a run thrown away, to start it over or because its task went cold.
+Removing deletes the harness folder with its notes, assets, history and uncommitted
+files, removes every worktree under `worktrees/` and deletes the local branches of the
+run; the task file and the remotes are not touched. Run it from the tasks repo, outside the harness: the
+command refuses to delete the folder it is run from, so a session inside the harness
+cannot remove it.
+
+1. **Identify the task by its ref**, as for a launch.
+2. **Read the `harness.remove` block:** run `gemba config show` and read
+   `processes.harness.remove` in the entry of `workstreams` whose `prefix` is the prefix
+   of the ref. Read `context` as background and follow every entry of `rules` before
+   showing the manifest.
+3. **Show the manifest** by running the command without `--yes`:
+
+   ```bash
+   gemba harness remove <ref>
+   ```
+
+   It prints the harness path, the task, the launch date and the number of notes,
+   assets, commits and worktrees (`worktrees:`), the number of uncommitted files of the
+   harness (`uncommitted:`) followed by one `- <path>` line per file, then
+   `not removed: pass --yes to delete the harness`, and deletes nothing.
+4. **Ask the user.** Show them the manifest, ask whether to delete the harness, its
+   worktrees and the local branches of the run, and remind them to close any IDE window
+   open on that folder first. When `uncommitted:` is not 0, name each path listed under
+   it, say that it is deleted with the harness, and say what would keep it should the
+   user want to, from a session inside the harness: a draft under `notes/` is filed with
+   `gemba harness note`, an `update.md` is recorded with `gemba record`; anything else
+   they may copy elsewhere. Never file, commit or delete any of them yourself. A yes in the conversation is enough here: the harness,
+   its worktrees and their branches are local, so no `external-action` note is needed.
+5. **Delete only after a yes**, by running the same command with `--yes`:
+
+   ```bash
+   gemba harness remove <ref> --yes
+   ```
+
+   When the user says no, stop.
+6. **Relay the result**: `removed` when the harness is gone. A later
+   `gemba harness launch <ref>` creates a fresh harness for the same task.
+
+When the command prints `harness not removed:`, in either step, relay every line and
+tell the user how each one is saved, from a session inside the harness:
+
+- `worktrees/<repo> has N uncommitted paths`: a commit inside that worktree saves them,
+  and the commit then needs a push like any other.
+- `worktrees/<repo> has N commits not on any remote branch`: a push from inside the
+  worktree saves them, and it needs an `external-action` note whose frontmatter reads
+  `approved: true` and that names the branch of the remote.
+- `branch <branch> of <repo> has N commits not on any remote branch and no worktree`: a
+  branch of the run left by a harness deleted by hand. Only the user can push it, from
+  that repository; you never run git there.
+- `worktrees/<name> is not a worktree`: a folder gemba did not create there; the user
+  moves it elsewhere if it is needed.
+
+Saving is the user's decision, carried out in a session inside the harness: from the
+tasks repo, never file, commit, push or delete anything yourself to make the removal
+pass, and never delete the folder by other means.
+
+**Never force first.** `--force` discards the uncommitted paths and unpushed commits of
+the worktrees, the unpushed commits of the branches of the run and the folders that are
+not worktrees. Never pass it on the first run, even when the user asks to force the
+removal: run the command without it, relay every line it reports, and pass
+`--yes --force` only after the user confirms, in the conversation, that everything in
+that list is to be discarded. `--force` never covers a working directory inside the
+harness nor a harness repository whose state cannot be read: those still refuse.
+
+## Rules
+
+- Commands own the frontmatter of the task and of every note, and `harness.yaml`; you
+  own the bodies of the notes. `task.md` is read-only.
+- Nothing outside the harness happens without an `external-action` note whose
+  frontmatter reads `approved: true`.
+- 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.