From 1d4e67f1857d819566ef3f4a8203f4533d182554 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 30 Jul 2026 07:53:53 +0100 Subject: [PATCH 1/2] docs(agents): describe the design, not the change to it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three authoring rules under Code and doc style, each earned during the #346 work: - Definitions, code and doc comments, and commit subjects state the system as it is. A commit subject is a permanent log entry, so `move usage accounting off the transition and onto the dispatch` makes a future reader learn the old model just to parse it; `account for token usage per dispatch` needs nothing. PR and issue bodies are the carve-out — a reviewer needs the before-state, and those stop being read once merged. Includes the sweep habit, because two stale descriptions of replaced behaviour survived a first pass and only a deliberate grep found them. - Prose warning "do not also use X" usually means two paths now do one job. Retire one and the warning has nothing to say, along with any validation that existed only to police the overlap — which is how a tool parameter, a validation warning and its test all left together rather than being documented around. - Sync CLAUDE.md and AGENTS.md by merging, never copying. That last one is why this commit also reconciles the two files. They had diverged: CLAUDE.md carried the #327 guard, worktree-provision and triage guidance; AGENTS.md carried the GitHub auth-and-shell section. Each had been overwritten by the other at some point, so both were missing content the other still had. This is the union — verified line-by-line against both prior versions, with nothing from either dropped. Every script the restored lines document is still in package.json. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 11 ++++++++++- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 542d16f9f..281d83bdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,20 +12,28 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, - **Build:** `npm run build` - **Run (stdio, default):** `npm start` or `npm run dev` - **Run (HTTP):** `npm run start:http` or `npm run dev:http` -- **Tests:** `npm test` +- **Tests:** `npm test` (watch) / `npm run test:ci` (single run) - **Typecheck:** `npm run typecheck` +- **Guards:** `npm run check:all` (every guard, one table) / `npm run check:delta` (only what your change added, against the merge-base) +- **Worktree setup:** `npm run worktree:provision` — checks out the submodules and makes `node_modules` resolvable, so guards and tests measure the worktree you are editing - **Workflow data:** `git worktree add ./workflows workflows` (see [README.md](README.md), [setup.md](setup.md), [stdio.md](stdio.md), [http.md](http.md)). ## Code and doc style - TypeScript; follow existing patterns in `src/` and `schemas/`. - Use clear, professional language; no process attribution in code comments (e.g. “Added by agent”). +- **Describe the design, not the change to it.** Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and **commit subjects** state the system as it is. A reader next year has no memory of the previous design, so naming it makes them learn it just to parse the sentence. Write `account for token usage per dispatch`, not `move usage accounting off the transition and onto the dispatch`; write `cost travels on its own call`, not `a transition can only account for a dispatch it exits`. Same for a value's absence: say what holds when it is missing, not what the old path did. + - **PR and issue bodies are the exception.** They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists. + - After a behaviour change, sweep for surviving descriptions of the old behaviour: doc comments, tool descriptions, technique `## Rules`, resource prose, READMEs. A grep for the old phrasing finds most of them; a stale claim reads as current fact. +- **Prefer removing the thing that needs a prohibition.** When a change leaves prose warning "do not also use X", that usually means two paths now do one job. Retire one and the warning has nothing left to say — along with any validation or edge-case handling that existed only to police the overlap. +- **Keep `CLAUDE.md` and `AGENTS.md` in sync by merging, never by copying.** They have diverged before, each gaining content the other lacked; overwriting one with the other silently drops the difference. ## Task management - Complete **one** task at a time unless the user asks for multiple. - For multi-step work, use todos and mark them complete as you finish; only one todo in progress at a time. - Request permission before starting a new task or making changes outside the current request. +- *ALWAYS* use a local work-tree when working on a branch ## Boundaries @@ -35,6 +43,7 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, ## Testing and PR instructions - After code or schema changes, run `npm run typecheck` and `npm test` before committing. +- After workflow-corpus changes, run `npm run check:all`. To see only what your change added, run `npm run check:delta`. Corpus debt is triaged per finding in `scripts/binding-fidelity-triage.json` — classify a new finding there (`harmless` / `fix-later` / `live-bug`) rather than suppressing it; there is no re-snapshot command. - Follow the repo’s PR/commit conventions. - **GitHub CLI — REST only (no GraphQL).** `gh pr create`, `gh pr view`, `gh pr list`, and any call that hits `api.github.com/graphql` are **forbidden** here (GraphQL is deprecated/unreliable and fails). Create and manage PRs with REST only, e.g.: diff --git a/CLAUDE.md b/CLAUDE.md index fa0042846..5201b9e89 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,12 +22,18 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, - TypeScript; follow existing patterns in `src/` and `schemas/`. - Use clear, professional language; no process attribution in code comments (e.g. “Added by agent”). +- **Describe the design, not the change to it.** Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and **commit subjects** state the system as it is. A reader next year has no memory of the previous design, so naming it makes them learn it just to parse the sentence. Write `account for token usage per dispatch`, not `move usage accounting off the transition and onto the dispatch`; write `cost travels on its own call`, not `a transition can only account for a dispatch it exits`. Same for a value's absence: say what holds when it is missing, not what the old path did. + - **PR and issue bodies are the exception.** They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists. + - After a behaviour change, sweep for surviving descriptions of the old behaviour: doc comments, tool descriptions, technique `## Rules`, resource prose, READMEs. A grep for the old phrasing finds most of them; a stale claim reads as current fact. +- **Prefer removing the thing that needs a prohibition.** When a change leaves prose warning "do not also use X", that usually means two paths now do one job. Retire one and the warning has nothing left to say — along with any validation or edge-case handling that existed only to police the overlap. +- **Keep `CLAUDE.md` and `AGENTS.md` in sync by merging, never by copying.** They have diverged before, each gaining content the other lacked; overwriting one with the other silently drops the difference. ## Task management - Complete **one** task at a time unless the user asks for multiple. - For multi-step work, use todos and mark them complete as you finish; only one todo in progress at a time. - Request permission before starting a new task or making changes outside the current request. +- *ALWAYS* use a local work-tree when working on a branch ## Boundaries @@ -49,6 +55,43 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, Other ops: `gh api repos/...`, `gh api --method PATCH|POST|GET ...`. Never use `gh pr *`. +### GitHub auth and agent shell (required) + +Host auth is normally **keyring + SSH** (`gh` logged in as the active user; `origin` is `git@github.com:...`). Most agent GitHub failures are environment mistakes, not a broken login. + +1. **Do not set `GH_TOKEN` or `GITHUB_TOKEN` unless you have a known-good PAT.** + `gh` prefers those env vars over keyring. A wrong or garbage value (including accidentally exporting command output into `GH_TOKEN`) yields `Bad credentials` / HTTP 401 even when `gh auth status` still shows a valid keyring login as inactive. + +2. **If auth looks wrong, clear env overrides and retry:** + + ```bash + unset GH_TOKEN GITHUB_TOKEN + gh auth status + gh api user --jq .login + ``` + + Prefer bare `gh` / `git` with keyring. Never scrape `~/.config/gh/hosts.yml` into `GH_TOKEN` (tokens live in the keyring, not that file). + +3. **Run real GitHub network/SSH ops outside the Cursor sandbox.** + Default sandboxed shells remap UIDs and break OpenSSH system config checks, typically: + + ```text + Bad owner or permissions on /etc/ssh/ssh_config.d/20-systemd-ssh-proxy.conf + fatal: Could not read from remote repository. + ``` + + For `git fetch` / `pull` / `push` / `ls-remote`, `ssh -T git@github.com`, and `gh api` against github.com, request full host permissions (unsandboxed), e.g. Shell `required_permissions: ["all"]`. Sandbox + SSH remotes + keyring do not mix reliably here. + +4. **Quick health check** (unsandboxed): + + ```bash + unset GH_TOKEN GITHUB_TOKEN + gh auth status + gh api user --jq .login + ssh -T git@github.com + git ls-remote origin HEAD + ``` + ## Where to look - **Quick start, schema, API:** [README.md](README.md), [schemas/README.md](schemas/README.md), [docs/api-reference.md](docs/api-reference.md) From 618d9ff43ba82674bb6330840c1d9307e905e129 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 30 Jul 2026 08:25:01 +0100 Subject: [PATCH 2/2] docs(agents): commit incrementally, and reserve force-push for one case MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Under Testing and PR instructions: each change lands as its own commit with its own message, pushed with plain git push. Where a push will not fast-forward, stop and ask rather than rewriting. Force-push has exactly one legitimate use — correcting a genuine error in an earlier commit, on a branch with no other contributors. Not squashing, not rewording, not folding a follow-up into the commit it fixes, never on a shared branch. The rule records why: repeated amending collapses distinct pieces of work into one commit, and the intermediate states then exist only in a local reflog. That loss is not recoverable, only reconstructable by hand — itself a rewrite. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 3 +++ CLAUDE.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 281d83bdd..42868bd78 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,9 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, - After code or schema changes, run `npm run typecheck` and `npm test` before committing. - After workflow-corpus changes, run `npm run check:all`. To see only what your change added, run `npm run check:delta`. Corpus debt is triaged per finding in `scripts/binding-fidelity-triage.json` — classify a new finding there (`harmless` / `fix-later` / `live-bug`) rather than suppressing it; there is no re-snapshot command. - Follow the repo’s PR/commit conventions. +- **Commit incrementally. Do not amend or squash to tidy up.** Each change lands as its own commit with its own message, so the branch carries a readable record of how it was built. Push with plain `git push`; when a push will not fast-forward, stop and ask rather than rewriting. + - **`--force`/`--force-with-lease` has exactly one use:** correcting a genuine error in an earlier commit, on a branch with **no other contributors**. Not for squashing, not for rewording, not for folding a follow-up into the commit it fixes, and never on a shared branch. + - Repeated amending is the failure mode to avoid: it silently collapses distinct pieces of work into one commit, and the intermediate states survive only in a local reflog. Once collapsed, the history cannot be recovered — only reconstructed by hand, which is a rewrite of its own. - **GitHub CLI — REST only (no GraphQL).** `gh pr create`, `gh pr view`, `gh pr list`, and any call that hits `api.github.com/graphql` are **forbidden** here (GraphQL is deprecated/unreliable and fails). Create and manage PRs with REST only, e.g.: ```bash diff --git a/CLAUDE.md b/CLAUDE.md index 5201b9e89..01af212a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,6 +45,9 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript, - After code or schema changes, run `npm run typecheck` and `npm test` before committing. - After workflow-corpus changes, run `npm run check:all`. To see only what your change added, run `npm run check:delta`. Corpus debt is triaged per finding in `scripts/binding-fidelity-triage.json` — classify a new finding there (`harmless` / `fix-later` / `live-bug`) rather than suppressing it; there is no re-snapshot command. - Follow the repo’s PR/commit conventions. +- **Commit incrementally. Do not amend or squash to tidy up.** Each change lands as its own commit with its own message, so the branch carries a readable record of how it was built. Push with plain `git push`; when a push will not fast-forward, stop and ask rather than rewriting. + - **`--force`/`--force-with-lease` has exactly one use:** correcting a genuine error in an earlier commit, on a branch with **no other contributors**. Not for squashing, not for rewording, not for folding a follow-up into the commit it fixes, and never on a shared branch. + - Repeated amending is the failure mode to avoid: it silently collapses distinct pieces of work into one commit, and the intermediate states survive only in a local reflog. Once collapsed, the history cannot be recovered — only reconstructed by hand, which is a rewrite of its own. - **GitHub CLI — REST only (no GraphQL).** `gh pr create`, `gh pr view`, `gh pr list`, and any call that hits `api.github.com/graphql` are **forbidden** here (GraphQL is deprecated/unreliable and fails). Create and manage PRs with REST only, e.g.: ```bash