gemba-cli 0.1.0__tar.gz

gemba_cli-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+.venv/
+.ruff_cache/
+dist/

gemba_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to the gemba CLI are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html): while the major version is
+0, a minor version may change a command or a file format, and the entry says so.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-11
+
+The first release: the whole cycle of a task, from a tasks repo that `gemba init`
+creates to the report of a period.
+
+### Added
+
+- `gemba init`, which makes a folder a tasks repo, and the `gemba-init` skill, the
+  guided first configuration.
+- `gemba.yaml`, the gemba config: workstreams with their prefixes, typed metadata
+  fields (`text`, `number`, `boolean`, `date`), agent providers, the IDE command, the
+  organization, the repositories folder, and `context` and `rules` per process, at the
+  top level and per workstream; `gemba config check` and `gemba config show`, and the
+  `gemba-config` skill that holds the reference of every key.
+- `gemba create`, `gemba list`, `gemba set`, `gemba mark` and `gemba archive`, each with
+  its skill: the frontmatter of a task is written by commands only, refs are never
+  reused, and listings and reports read every task file and report the invalid ones.
+- `gemba harness launch`, `note`, `resolve` and `remove`: the harness of a run, its own
+  git repository with the guide of the agent, the filed notes and their approval gate
+  for actions outside the harness.
+- `gemba worktree add`, `list` and `remove`: git worktrees of the organization's
+  repositories inside a harness, each on the local branch of the run, never pushed
+  under its own name.
+- `gemba record` and the `gemba-report` skill: the update of a day written into the
+  task from a draft, and the report of a day, a week or a month, with every count and
+  sum taken from `gemba report`.
+- `gemba skills update`: the skills ship with the package and are written into the
+  tasks repo and into each harness for every agent provider declared, with their
+  provenance, so an upgrade refreshes them and a hand edit is kept.
+
+[Unreleased]: https://github.com/web-crafts-org/gemba/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/web-crafts-org/gemba/releases/tag/v0.1.0

gemba_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Robles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gemba_cli-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.5
+Name: gemba-cli
+Version: 0.1.0
+Summary: Gemba: a task-based system for working with AI agents
+Project-URL: Repository, https://github.com/web-crafts-org/gemba
+Project-URL: Changelog, https://github.com/web-crafts-org/gemba/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/web-crafts-org/gemba/issues
+Author: Manuel Robles
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-harness,agent-skills,agentic-development,ai-agents,claude-code,cli,codex,context-engineering,harness,task-management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+# Gemba
+
+Gemba is a task-based system for working with AI agents. Every unit of work is one
+Markdown file in a repository of your own, your agent registers, launches, updates and
+closes those tasks through fixed processes, and each task is worked on inside a
+harness: a folder of its own, with its notes, its evidence and the code it touches,
+where nothing leaves without your written approval. Everything that is specific to one
+organization, its kinds of work, its fields, its rules, lives in one config file, so
+you keep one tasks repo per organization and the agent behaves the same in all of them.
+
+The name is 現場, *gemba*: "the actual place", where the work happens. In Gemba that
+place is the harness, a folder made for one task, where the agent works on it and on
+nothing else, with everything the task needs inside and none of the noise of every
+other pending thing. The task file is the logbook of that work: what was done, when,
+and what it cost, recorded day by day. The harness is where the work gets done; the
+task file is where you learn from it, the record that over time lets you see how you
+work, measure it and improve it.
+
+## The idea
+
+```
+  your tasks repo                                  the harness of one run
+  +-------------------------------------+          +--------------------------------+
+  | gemba.yaml   your organization:     |  launch  | task.md     the task, read-only|
+  |              workstreams, fields,   | -------> | notes/      what the agent     |
+  |              rules per process      |          |             found and decided  |
+  | tasks/       one file per task,     |          | assets/     the raw evidence   |
+  |              a ref like SUP-12      |  record  | worktrees/  the repositories,  |
+  | .claude/     the skills: the        | <------- |             one branch per run |
+  |   skills/    processes the agent    |          | CLAUDE.md   the guide of the   |
+  |              follows                |          |             agent              |
+  +-------------------------------------+          +--------------------------------+
+```
+
+The cycle of a task:
+
+```
+  create --> launch --> work in the harness --> record the day --> mark done
+                          notes, worktrees,         |                  |
+                          approved actions          v                  v
+                                                 report             archive,
+                                                 of the period      remove the harness
+```
+
+Three things keep it honest:
+
+- **Commands own the frontmatter, agents own the body.** The status, the dates and the
+  metadata of a task are written only by `gemba` commands; the agent writes prose.
+- **Nothing leaves the harness without an approved note.** A push, a message, a
+  deployment: the agent writes what it is about to do, and you approve it by editing
+  the note. A yes in the chat does not count.
+- **Every number comes from a command.** Counts and totals in a report are computed
+  by `gemba report`, never by the agent.
+
+Gemba works with any agent that reads skills from a folder: Claude Code
+(`.claude/skills/`) and the agents that read `.agents/skills/` (Codex, Cursor,
+Gemini CLI and others) are built in.
+
+## Install and start
+
+The only prerequisite is [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install gemba-cli
+gemba --version
+gemba init ~/nakatomi-tasks       # a tasks repo for the organization you work with
+```
+
+`gemba init` writes a minimal `gemba.yaml`, the `tasks/` folder, a `.gitignore` and
+the skills for every agent it knows (`--providers claude` keeps only one). It runs no
+git: make the folder a repository and commit it when you like.
+
+Then open the folder with your agent and ask it to configure Gemba. The `gemba-init`
+skill asks, one question at a time, for your organization, the kinds of work you do,
+which one takes a task that fits no other, what to record per task, your agents, your
+editor and the folder of your repositories, and writes the answers into `gemba.yaml`.
+
+From there, talk to the agent:
+
+> Register a task: login fails on Safari for Acme's checkout app.
+
+> Launch SUP-1.
+
+> Record the day on this task.
+
+> What did I do this week?
+
+## The cycle of a task
+
+Each step is a skill the agent follows and a command the skill runs. You can run the
+commands yourself too; every one of them prints what it did or every problem it found,
+at once, and exits 1 without writing anything when it refuses.
+
+### Register
+
+The `gemba-create` skill picks the workstream from the descriptions in `gemba.yaml`,
+asks for any required field you did not give, and runs:
+
+```bash
+gemba create --workstream support --slug login-fails-on-safari \
+  --description "Login fails on Safari for the checkout app" --set client=acme
+```
+
+The task file is `tasks/support/2026-09-30-SUP-1-login-fails-on-safari.md`:
+
+```markdown
+---
+status: open
+ref: SUP-1
+updated_at: 2026-09-30
+metadata:
+  client: acme
+  hours: null
+---
+
+Login fails on Safari for the checkout app
+
+## Updates
+```
+
+The ref is allocated from the highest number already used, archives included, so it
+is never reused. The metadata keys are exactly the ones declared for that workstream,
+present even when unset, each read, compared and added by the type its field declares.
+
+### Launch
+
+```bash
+gemba harness launch SUP-1
+```
+
+creates `harnesses/support/2026-09-30-SUP-1-login-fails-on-safari/` as a git
+repository of its own, with `harness.yaml`, the run's identity; `task.md`, a link to
+the task; the guide of the agent (`CLAUDE.md`, `AGENTS.md`); the harness skills;
+`notes/`, `assets/` and `worktrees/`. It moves an `open` task to `in-progress` and
+opens the folder with the `ide` command of `gemba.yaml` (`--no-open` skips it).
+Launching again only reopens it. `harnesses/` is ignored by the tasks repo: a run is
+not a record, the task is.
+
+### Work in the harness
+
+Start the agent inside the harness. The guide tells it to read the task and the notes
+first, to write before it acts, and to keep every finding, blocker, decision or
+summary as a small note, drafted as `notes/<slug>.md` and filed with the
+`gemba-harness` skill, which names it after the clock, writes its frontmatter and
+commits:
+
+```bash
+gemba harness note notes/login-trace.md --type finding --asset assets/1759350491-console.log
+```
+
+An `external-action` note describes, word for word, something to be done outside the
+harness. Nothing happens until you set `approved: true` in its frontmatter from your
+editor. After acting, the agent writes the outcome into the note and runs
+`gemba harness resolve notes/<file>.md`, which records when.
+
+When the task touches code, the agent checks out the repositories it needs as git
+worktrees, each on a local branch named after the run:
+
+```bash
+gemba worktree add nakatomi-web                      # from the default branch of origin
+gemba worktree add nakatomi-web --from release/2.4   # from another branch, or move to it
+gemba worktree list                                  # branch, upstream, uncommitted, unpushed
+gemba worktree remove nakatomi-web --yes             # the worktree and its branch
+```
+
+A repository is a folder under the `repos_dir` of `gemba.yaml`; Gemba never clones.
+The branch, `gemba/nakatomi/SUP-1`, exists only on your machine and is never pushed
+under its own name: a push needs an approved note naming the branch of the remote, and
+always names its target, `git push -u origin HEAD:<that branch>`. `add --from` and
+`remove` refuse while anything is uncommitted or on no remote branch; `--force`
+discards it, and the agent passes it only after you confirm what the command listed.
+
+### Record the day
+
+At the end of the day, ask the agent to record the day on the task. It distills the
+notes of that date into a few bullets in `update.md` at the harness root and runs:
+
+```bash
+gemba record update.md                     # today
+gemba record update.md --date 2026-09-30   # a past day
+```
+
+The bullets land under `### 2026-09-30` in the task's `## Updates` section,
+`updated_at` moves forward, and the draft is deleted. Nothing is committed: the tasks
+repo is yours to review and commit.
+
+### Report
+
+Ask the agent in the tasks repo for yesterday, for a day, a week or a month. The
+`gemba-report` skill finds the tasks alive in the period with `gemba list`, reads the
+subsections dated in it, groups what it finds by workstream, and lists the tasks
+updated recently with nothing recorded. Every count and total comes from:
+
+```bash
+gemba report --done-from 2026-09-01 --done-to 2026-09-30 --by client --sum hours
+```
+
+which takes the filters of `gemba list`, groups with `--by` (`workstream`, `status`,
+or a text or boolean field) and adds number fields with `--sum`, exactly.
+
+### Close out
+
+Three steps, each on its own, each asking before it deletes anything:
+
+```bash
+gemba mark SUP-1 done                  # done today: done_at and updated_at move
+gemba mark SUP-1 open                  # reopened: done_at is removed
+gemba harness remove SUP-1             # show what the run holds, delete nothing
+gemba harness remove SUP-1 --yes       # delete the harness, its worktrees and branches
+gemba archive SUP-1 OPS-2              # move each task file into archive/
+```
+
+A task done today can be reopened tomorrow in the same harness; a run can be thrown
+away on a task still in progress; a task is archived only once it went cold, and only
+after its harness is gone. Archived tasks leave `gemba list` unless
+`--include-archived` is given.
+
+### Keep the metadata
+
+The hours grow, the work gets invoiced. Tell the agent, from the tasks repo or inside
+the harness, and the `gemba-set` skill runs:
+
+```bash
+gemba set SUP-1 hours+=2                # added to the number the task holds
+gemba set SUP-1 invoiced=2026-10-03     # a value, written by the type of its field
+gemba set SUP-1 merge_requests=null     # cleared
+```
+
+It rewrites only the metadata, never `updated_at`, and refuses an undeclared key or a
+value of the wrong type.
+
+## The config
+
+`gemba.yaml` is edited by hand, or by the `gemba-config` skill when you ask the agent
+to add a workstream, a field or a rule; `gemba config check` validates it and
+`gemba config show` prints it resolved, as the skills read it. No command rewrites it.
+
+```yaml
+default_workstream: operations
+
+agent_providers: [claude, agents]
+
+ide: code -n
+organization: nakatomi
+repos_dir: ~/projects
+
+metadata:
+  - { name: client, type: text, required: true, description: Who the work is for }
+  - { name: hours, type: number, description: Total hours spent on the task }
+  - { name: invoiced, type: date, description: When the work was invoiced }
+
+harness:
+  guide: |
+    Client data never leaves the harness: strip it from every asset you save.
+
+workstreams:
+  support:
+    prefix: SUP
+    description: Investigate a client-reported problem and deliver a report or a fix
+    worktree:
+      add:
+        rules:
+          - start from the branch deployed to production; ask when the task does not say it
+  operations:
+    prefix: OPS
+    description: Anything that does not fit another workstream
+```
+
+What you can customize, all of it here and never in a skill:
+
+- **Workstreams**, each with a prefix, a description the agent uses to choose one, and
+  its own fields, and the one that takes a task that fits no other.
+- **Metadata fields**, shared or per workstream, each of one type: `text`, `number`,
+  `boolean` or `date`. Gemba reads, filters, groups and adds values by their type and
+  never interprets their meaning.
+- **Agent providers**, the IDE command, the organization and the repositories folder.
+- **`context` and `rules` for every process**, at the top level and per workstream:
+  what the agent should know and do when it creates, lists, launches, notes, records,
+  marks, archives or checks out, with the workstream's rule winning a contradiction.
+- **The guide** of every harness, with a paragraph of your organization and one of
+  the workstream.
+
+Changing any of it is a config edit: no skill and no code changes.
+
+## Status
+
+Gemba is young, at version 0.x, and built from daily use: the whole cycle above
+works, and the shape of the commands may still change between minor versions, with
+the changelog saying so. Ideas, questions and reports of what got in your way are the
+most useful contribution right now: see [CONTRIBUTING.md](CONTRIBUTING.md), which also
+describes how the product is developed, by specification, one case per scenario.
+
+## License
+
+[MIT](LICENSE).

gemba_cli-0.1.0/README.md

@@ -0,0 +1,295 @@
+# Gemba
+
+Gemba is a task-based system for working with AI agents. Every unit of work is one
+Markdown file in a repository of your own, your agent registers, launches, updates and
+closes those tasks through fixed processes, and each task is worked on inside a
+harness: a folder of its own, with its notes, its evidence and the code it touches,
+where nothing leaves without your written approval. Everything that is specific to one
+organization, its kinds of work, its fields, its rules, lives in one config file, so
+you keep one tasks repo per organization and the agent behaves the same in all of them.
+
+The name is 現場, *gemba*: "the actual place", where the work happens. In Gemba that
+place is the harness, a folder made for one task, where the agent works on it and on
+nothing else, with everything the task needs inside and none of the noise of every
+other pending thing. The task file is the logbook of that work: what was done, when,
+and what it cost, recorded day by day. The harness is where the work gets done; the
+task file is where you learn from it, the record that over time lets you see how you
+work, measure it and improve it.
+
+## The idea
+
+```
+  your tasks repo                                  the harness of one run
+  +-------------------------------------+          +--------------------------------+
+  | gemba.yaml   your organization:     |  launch  | task.md     the task, read-only|
+  |              workstreams, fields,   | -------> | notes/      what the agent     |
+  |              rules per process      |          |             found and decided  |
+  | tasks/       one file per task,     |          | assets/     the raw evidence   |
+  |              a ref like SUP-12      |  record  | worktrees/  the repositories,  |
+  | .claude/     the skills: the        | <------- |             one branch per run |
+  |   skills/    processes the agent    |          | CLAUDE.md   the guide of the   |
+  |              follows                |          |             agent              |
+  +-------------------------------------+          +--------------------------------+
+```
+
+The cycle of a task:
+
+```
+  create --> launch --> work in the harness --> record the day --> mark done
+                          notes, worktrees,         |                  |
+                          approved actions          v                  v
+                                                 report             archive,
+                                                 of the period      remove the harness
+```
+
+Three things keep it honest:
+
+- **Commands own the frontmatter, agents own the body.** The status, the dates and the
+  metadata of a task are written only by `gemba` commands; the agent writes prose.
+- **Nothing leaves the harness without an approved note.** A push, a message, a
+  deployment: the agent writes what it is about to do, and you approve it by editing
+  the note. A yes in the chat does not count.
+- **Every number comes from a command.** Counts and totals in a report are computed
+  by `gemba report`, never by the agent.
+
+Gemba works with any agent that reads skills from a folder: Claude Code
+(`.claude/skills/`) and the agents that read `.agents/skills/` (Codex, Cursor,
+Gemini CLI and others) are built in.
+
+## Install and start
+
+The only prerequisite is [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv tool install gemba-cli
+gemba --version
+gemba init ~/nakatomi-tasks       # a tasks repo for the organization you work with
+```
+
+`gemba init` writes a minimal `gemba.yaml`, the `tasks/` folder, a `.gitignore` and
+the skills for every agent it knows (`--providers claude` keeps only one). It runs no
+git: make the folder a repository and commit it when you like.
+
+Then open the folder with your agent and ask it to configure Gemba. The `gemba-init`
+skill asks, one question at a time, for your organization, the kinds of work you do,
+which one takes a task that fits no other, what to record per task, your agents, your
+editor and the folder of your repositories, and writes the answers into `gemba.yaml`.
+
+From there, talk to the agent:
+
+> Register a task: login fails on Safari for Acme's checkout app.
+
+> Launch SUP-1.
+
+> Record the day on this task.
+
+> What did I do this week?
+
+## The cycle of a task
+
+Each step is a skill the agent follows and a command the skill runs. You can run the
+commands yourself too; every one of them prints what it did or every problem it found,
+at once, and exits 1 without writing anything when it refuses.
+
+### Register
+
+The `gemba-create` skill picks the workstream from the descriptions in `gemba.yaml`,
+asks for any required field you did not give, and runs:
+
+```bash
+gemba create --workstream support --slug login-fails-on-safari \
+  --description "Login fails on Safari for the checkout app" --set client=acme
+```
+
+The task file is `tasks/support/2026-09-30-SUP-1-login-fails-on-safari.md`:
+
+```markdown
+---
+status: open
+ref: SUP-1
+updated_at: 2026-09-30
+metadata:
+  client: acme
+  hours: null
+---
+
+Login fails on Safari for the checkout app
+
+## Updates
+```
+
+The ref is allocated from the highest number already used, archives included, so it
+is never reused. The metadata keys are exactly the ones declared for that workstream,
+present even when unset, each read, compared and added by the type its field declares.
+
+### Launch
+
+```bash
+gemba harness launch SUP-1
+```
+
+creates `harnesses/support/2026-09-30-SUP-1-login-fails-on-safari/` as a git
+repository of its own, with `harness.yaml`, the run's identity; `task.md`, a link to
+the task; the guide of the agent (`CLAUDE.md`, `AGENTS.md`); the harness skills;
+`notes/`, `assets/` and `worktrees/`. It moves an `open` task to `in-progress` and
+opens the folder with the `ide` command of `gemba.yaml` (`--no-open` skips it).
+Launching again only reopens it. `harnesses/` is ignored by the tasks repo: a run is
+not a record, the task is.
+
+### Work in the harness
+
+Start the agent inside the harness. The guide tells it to read the task and the notes
+first, to write before it acts, and to keep every finding, blocker, decision or
+summary as a small note, drafted as `notes/<slug>.md` and filed with the
+`gemba-harness` skill, which names it after the clock, writes its frontmatter and
+commits:
+
+```bash
+gemba harness note notes/login-trace.md --type finding --asset assets/1759350491-console.log
+```
+
+An `external-action` note describes, word for word, something to be done outside the
+harness. Nothing happens until you set `approved: true` in its frontmatter from your
+editor. After acting, the agent writes the outcome into the note and runs
+`gemba harness resolve notes/<file>.md`, which records when.
+
+When the task touches code, the agent checks out the repositories it needs as git
+worktrees, each on a local branch named after the run:
+
+```bash
+gemba worktree add nakatomi-web                      # from the default branch of origin
+gemba worktree add nakatomi-web --from release/2.4   # from another branch, or move to it
+gemba worktree list                                  # branch, upstream, uncommitted, unpushed
+gemba worktree remove nakatomi-web --yes             # the worktree and its branch
+```
+
+A repository is a folder under the `repos_dir` of `gemba.yaml`; Gemba never clones.
+The branch, `gemba/nakatomi/SUP-1`, exists only on your machine and is never pushed
+under its own name: a push needs an approved note naming the branch of the remote, and
+always names its target, `git push -u origin HEAD:<that branch>`. `add --from` and
+`remove` refuse while anything is uncommitted or on no remote branch; `--force`
+discards it, and the agent passes it only after you confirm what the command listed.
+
+### Record the day
+
+At the end of the day, ask the agent to record the day on the task. It distills the
+notes of that date into a few bullets in `update.md` at the harness root and runs:
+
+```bash
+gemba record update.md                     # today
+gemba record update.md --date 2026-09-30   # a past day
+```
+
+The bullets land under `### 2026-09-30` in the task's `## Updates` section,
+`updated_at` moves forward, and the draft is deleted. Nothing is committed: the tasks
+repo is yours to review and commit.
+
+### Report
+
+Ask the agent in the tasks repo for yesterday, for a day, a week or a month. The
+`gemba-report` skill finds the tasks alive in the period with `gemba list`, reads the
+subsections dated in it, groups what it finds by workstream, and lists the tasks
+updated recently with nothing recorded. Every count and total comes from:
+
+```bash
+gemba report --done-from 2026-09-01 --done-to 2026-09-30 --by client --sum hours
+```
+
+which takes the filters of `gemba list`, groups with `--by` (`workstream`, `status`,
+or a text or boolean field) and adds number fields with `--sum`, exactly.
+
+### Close out
+
+Three steps, each on its own, each asking before it deletes anything:
+
+```bash
+gemba mark SUP-1 done                  # done today: done_at and updated_at move
+gemba mark SUP-1 open                  # reopened: done_at is removed
+gemba harness remove SUP-1             # show what the run holds, delete nothing
+gemba harness remove SUP-1 --yes       # delete the harness, its worktrees and branches
+gemba archive SUP-1 OPS-2              # move each task file into archive/
+```
+
+A task done today can be reopened tomorrow in the same harness; a run can be thrown
+away on a task still in progress; a task is archived only once it went cold, and only
+after its harness is gone. Archived tasks leave `gemba list` unless
+`--include-archived` is given.
+
+### Keep the metadata
+
+The hours grow, the work gets invoiced. Tell the agent, from the tasks repo or inside
+the harness, and the `gemba-set` skill runs:
+
+```bash
+gemba set SUP-1 hours+=2                # added to the number the task holds
+gemba set SUP-1 invoiced=2026-10-03     # a value, written by the type of its field
+gemba set SUP-1 merge_requests=null     # cleared
+```
+
+It rewrites only the metadata, never `updated_at`, and refuses an undeclared key or a
+value of the wrong type.
+
+## The config
+
+`gemba.yaml` is edited by hand, or by the `gemba-config` skill when you ask the agent
+to add a workstream, a field or a rule; `gemba config check` validates it and
+`gemba config show` prints it resolved, as the skills read it. No command rewrites it.
+
+```yaml
+default_workstream: operations
+
+agent_providers: [claude, agents]
+
+ide: code -n
+organization: nakatomi
+repos_dir: ~/projects
+
+metadata:
+  - { name: client, type: text, required: true, description: Who the work is for }
+  - { name: hours, type: number, description: Total hours spent on the task }
+  - { name: invoiced, type: date, description: When the work was invoiced }
+
+harness:
+  guide: |
+    Client data never leaves the harness: strip it from every asset you save.
+
+workstreams:
+  support:
+    prefix: SUP
+    description: Investigate a client-reported problem and deliver a report or a fix
+    worktree:
+      add:
+        rules:
+          - start from the branch deployed to production; ask when the task does not say it
+  operations:
+    prefix: OPS
+    description: Anything that does not fit another workstream
+```
+
+What you can customize, all of it here and never in a skill:
+
+- **Workstreams**, each with a prefix, a description the agent uses to choose one, and
+  its own fields, and the one that takes a task that fits no other.
+- **Metadata fields**, shared or per workstream, each of one type: `text`, `number`,
+  `boolean` or `date`. Gemba reads, filters, groups and adds values by their type and
+  never interprets their meaning.
+- **Agent providers**, the IDE command, the organization and the repositories folder.
+- **`context` and `rules` for every process**, at the top level and per workstream:
+  what the agent should know and do when it creates, lists, launches, notes, records,
+  marks, archives or checks out, with the workstream's rule winning a contradiction.
+- **The guide** of every harness, with a paragraph of your organization and one of
+  the workstream.
+
+Changing any of it is a config edit: no skill and no code changes.
+
+## Status
+
+Gemba is young, at version 0.x, and built from daily use: the whole cycle above
+works, and the shape of the commands may still change between minor versions, with
+the changelog saying so. Ideas, questions and reports of what got in your way are the
+most useful contribution right now: see [CONTRIBUTING.md](CONTRIBUTING.md), which also
+describes how the product is developed, by specification, one case per scenario.
+
+## License
+
+[MIT](LICENSE).