chore(release): merge release/0.2.0 into main

.agents/skills/git-commit

@@ -0,0 +1 @@
+../../skills/engineering/git-commit

.claude/skills/git-commit

@@ -0,0 +1 @@
+../../skills/engineering/git-commit

.gitignore

@@ -5,5 +5,6 @@ CLAUDE.local.md
 skills-lock.json
 !tests/**/project/.claude/
 !tests/**/project/.agents/
+tests/**/project/.agents/skills/agent-instructions/
 node_modules/
 .playwright-mcp/

AGENTS.md

@@ -1,30 +1,29 @@
 # System design
 
-- Treat evidence-led KISS and YAGNI as equal primary system design heuristics.
-- Consider SOLID for every system design decision, and prefer composition over inheritance.
-- Design functionality and tests around standard usage and feasible failures reachable through production inputs, dependencies, or execution paths. Failures possible only through test-only construction are outside scope.
+- Use KISS and YAGNI as the two equal primary rules of system design. Base each design decision on evidence.
+- For each system design decision, examine SOLID. Use composition, not inheritance.
+- Design the code and its tests for standard use, and for the failures that production inputs, dependencies, or code paths can cause. Do not design for failures that only test code can cause.
 
 # Questions
 
-- Ask one question at a time through the question harness tool, and wait for the answer before the next. Provide concrete answer options, with the recommended option first. This sequence replaces any skill's batched-round format.
+- When you must ask the operator a question, use the question tool. Ask one question, then wait for the answer before you ask the next question. Give concrete answer options, with the recommended option first. This rule replaces the question format of each Skill that asks questions in batches.
 
 # Knowledge
 
 - Before you examine or change the repository, read `GLOSSARY.md` for the project terms and `MEMORY.md` for the applicable entries. Before you change a part of the project, read the ADRs in `docs/adr/` that are related to that part. Obey these ADRs, because each ADR records a decision that the code does not show.
-- Prototypes: `prototypes/` holds throwaway work. Take facts and decisions from the rest of the repo, and open `prototypes/` only when the human's current prompt asks for it.
+- Prototypes: The `prototypes/` folder contains work that the repository does not keep. Take facts and decisions from the other folders. Open `prototypes/` only when the current prompt of the operator tells you to open it.
 
 # Workflow
 
-- Branches: Before creating a branch, opening or merging a pull request, follow Git Flow strictly. Open pull requests into `main` only from `release/<semver>` or `hotfix/<name>`. Send every other change, including `feature/<name>` and `bugfix/<name>`, through a pull request into `develop`. Change `main` and `develop` only through pull requests with merge commits, because users install skills from `main`.
-- Merging: Merge a pull request into `develop` yourself once every required check passes. Leave pull requests into `main` for the human to merge. GitHub deletes the remote branch of a merged pull request, but your local branch stays. After you merge a pull request from a `feature/<name>` or `bugfix/<name>` branch into `develop`, do these steps:
+- Branches: Before you create a branch, or open or merge a pull request, obey Git Flow. Open pull requests into `main` only from `release/<semver>` or `hotfix/<name>`. Send all other changes, for example `feature/<name>` and `bugfix/<name>`, through a pull request into `develop`. Change `main` and `develop` only through pull requests with merge commits, because other projects install Skills from `main`.
+- Merging: When all required checks pass, merge a pull request into `develop` yourself. For this merge commit, start the message with the line `<type>[(<scope>)]: merge <branch> into develop (#<n>)`. When you write this message, obey each Setting of the Commit policy, `docs/agents/commit-policy.md`, that controls the message. Leave pull requests into `main` for the operator to merge. GitHub deletes the remote branch of a merged pull request, but your local branch stays. After you merge a pull request from a `feature/<name>` or `bugfix/<name>` branch into `develop`, do these steps:
   1. Run `git switch develop`.
   2. Run `git pull`.
   3. Run `git fetch --prune`.
   4. CAUTION: Delete a local branch only with `git branch -d`, not `git branch -D`. `git branch -D` deletes commits that no other branch contains.
   5. Delete the local branch of that pull request with `git branch -d <branch>`.
-- Commits: Before creating a commit or proposing or using a commit message, read and follow [`docs/agents/commit-policy.md`](docs/agents/commit-policy.md).
-- Checks: Before each commit, run `docker compose run --rm bun run check`. Done when it exits 0; fix every error it reports. To fix formatting, run `docker compose run --rm bun run fix`.
-- Back-merges: After the user merges a pull request into `main`, `release.yml` opens the back-merge pull request from `main` into `develop`. If the `back-merge` job stops because Git cannot merge `main` into `develop`, do not change that pull request. If you change that pull request, you push commits to `main`. Run `git fetch`. Then do these steps:
+- Checks: Before each commit, run `docker compose run --rm bun run check`. Correct all errors that it reports, until it exits 0. To correct the format, run `docker compose run --rm bun run fix`.
+- Back-merges: After the operator merges a pull request into `main`, `release.yml` opens the back-merge pull request from `main` into `develop`. If the `back-merge` job stops because Git cannot merge `main` into `develop`, do not change that pull request. If you change that pull request, you push commits to `main`. Run `git fetch`. Then do these steps:
   1. Make the branch `bugfix/back-merge-v<semver>` from `origin/develop`. The title of the back-merge pull request gives `<semver>`.
   2. On that branch, run `git merge origin/main` and correct the files that Git cannot merge.
   3. Open a pull request from that branch into `develop`.
@@ -34,11 +33,11 @@
 
 ## Issue tracker
 
-GitHub Issues on a1exk-dev/agent-context, tracked in the private "agent-context" project. See `docs/agents/issue-tracker.md`.
+The issues are GitHub Issues on a1exk-dev/agent-context. The private "agent-context" project tracks them. Before you create, read, or change an issue, read `docs/agents/issue-tracker.md`.
 
 ## Triage labels
 
-Default labels: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See `docs/agents/triage-labels.md`.
+The default labels are needs-triage, needs-info, ready-for-agent, ready-for-human, and wontfix. Before you add or change a triage label, read `docs/agents/triage-labels.md`.
 
 ## Domain docs
 

GLOSSARY.md

@@ -18,3 +18,19 @@ A Category is a folder, one level deep, that contains Skills under `skills/` or
 **Agent instruction**:
 An Agent instruction is a file that an agent reads as instructions. Examples are a Skill, a Rule, `AGENTS.md`, `CLAUDE.md`, `GLOSSARY.md`, `MEMORY.md`, and the files in `docs/agents/`. A file for persons, for example `README.md`, is not an Agent instruction.
 _Avoid_: prompt file, instruction file
+
+**Operator**:
+The operator is the human who controls a project and the agents that work in it. Only the operator answers the questions of an agent and gives approval. An agent never acts as the operator.
+_Avoid_: user, owner, maintainer
+
+**Commit policy**:
+A Commit policy is the file `docs/agents/commit-policy.md` of a project. It holds the title `# Commit policy` and the Settings that each commit by the git-commit Skill obeys, and no other text.
+_Avoid_: commit rules, commit conventions, commit config
+
+**Setting**:
+A Setting is one line `- <name>: <value>` of a Commit policy. The git-commit Skill fixes each name and its possible values.
+_Avoid_: option, rule
+
+**Commit review**:
+A Commit review is what an agent shows the Operator before one commit: the staged files, the full diff, and the exact message. But for a diff of more than 500 lines, the Commit review gives the command that shows the diff, not the full diff. The commit occurs only after the Operator approves that review.
+_Avoid_: commit preview, approval request

cspell.json

@@ -21,6 +21,7 @@
         "gpgsign",
         "mattpocock",
         "mktemp",
+        "oneline",
         "opencode",
         "vitest",
         "wayfinder",

docs/agents/commit-policy.md

@@ -1,12 +1,12 @@
 # Commit policy
 
-- Follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). Scopes are optional.
-- Include a `Refs: #<issue-number>` footer in commits that work on an issue.
-- Apply the commit format and approval policy to every commit, including merge commits; this policy overrides skill defaults.
-- After approval, use the reviewed message without rewriting it.
-- Present verified changes and the proposed message for human review. Ask one question with `Commit`, `Request changes`, and `Reject` options when no decision is pending.
-- A `Commit` decision authorizes only the reviewed diff and message for one commit. Apply requested changes, verify them, and present them again. Leave rejected work uncommitted.
-
-## When GitHub merges the pull request from `main` into `develop` automatically
-
-- Do not ask for approval of the merge commit that has the message `chore: merge main v<semver> into develop (#<n>)`, because no agent makes this commit.
+- Scope: optional
+- Scopes: any
+- Types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
+- Breaking change: both
+- Issue footer: Refs
+- Header length: 72
+- Body: optional
+- Description style: lower case, imperative, no full stop
+- Commit approval: automatic
+- Push: automatic

docs/agents/domain.md

@@ -51,14 +51,14 @@ At the completion of every task, classify each useful discovery and important de
 
 Write each qualifying item automatically as soon as it is resolved, without an approval gate. For an ADR, obey the section "When a task makes an architecture decision". Keep each meaning in one authoritative file and update an existing entry instead of duplicating it. At task completion, run the classification once more to catch anything missed. Tasks with no qualifying durable knowledge finish without a knowledge-file edit.
 
-Commit every knowledge-file edit on the branch whose work produced it, before that branch is pushed, through the [commit policy](commit-policy.md)'s review. Preservation is complete when every qualifying item appears in exactly one authoritative location. In the final response, give the human a concise review list containing each changed knowledge file, what was added or updated, and why it qualified.
+Commit every knowledge-file edit on the branch whose work produced it, before that branch is pushed. Preservation is complete when every qualifying item appears in exactly one authoritative location. In the final response, give the human a concise review list containing each changed knowledge file, what was added or updated, and why it qualified.
 
 ## When a task makes an architecture decision
 
 1. When a task makes an architecture decision, use the `domain-modeling` skill to examine the decision.
-2. If all 3 conditions in the section "Offer ADRs sparingly" of the `domain-modeling` skill are true, recommend an ADR to the user. If not, write the decision in `MEMORY.md`.
-3. Before you write the ADR in `docs/adr/`, get approval from the user, because the user controls each ADR.
+2. If all 3 conditions in the section "Offer ADRs sparingly" of the `domain-modeling` skill are true, recommend an ADR to the operator. If not, write the decision in `MEMORY.md`.
+3. Before you write the ADR in `docs/adr/`, get approval from the operator, because the operator controls each ADR.
 
 ## Before you change an ADR
 
-- Get approval from the user, because the user controls each ADR.
+- Get approval from the operator, because the operator controls each ADR.