Skip to content

Commit 306380c

Browse files
cliffhallclaude
andcommitted
docs: address Copilot review on the inception doc
- Scope client evidence to server-facing changes, with a targeted probe otherwise, and require both clients consistently - HTTP+SSE is deprecated, not removed, in the 2026-07-28 spec - Scope labels only where an issue concerns one server - S7 depends on S5 and S8 - Release prep is up to three PRs under #4472's two bump PRs - Action pinning covers claude.yml too - Sweep dry runs write nothing Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent b1abd8a commit 306380c

1 file changed

Lines changed: 37 additions & 21 deletions

File tree

‎docs/agent-guidance-inception.md‎

Lines changed: 37 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ The **Sub-issue** column points into [§9](#9-proposed-sub-issues).
105105
| `board-ops` | `gh project` recipes for two boards; ID tables; resolving option IDs by name; the option-deletion hazard and its recovery | Adapt | One board, #43. Its fields: Status (with **Incoming**), Priority, Size. Hazard and recovery copy unchanged | S5 |
106106
| `issue-create` | Five-step create flow: version label, type label, milestone, card, Status + Priority; duplicate check across all states | Adapt | Version label is always `v2`. Add a **server-scope label** step (`server-<name>`). Milestone = nearest due v2.x | S5 |
107107
| `issue-triage` | Two-pass sweep (board as Incoming, then human approval), priority rubric with a score comment, 12-check board audit | Adapt | The **highest-leverage skill here** given the inflow (§3.4). Add spam/registry-redirect classes, server-scope labelling, and outside-PR triage | S7 |
108-
| `pr-flow` | Assign + In Progress, branch naming, DCO signoff, screenshots, `Closes #N`, `addCloseIssueReferences`, In Review, Copilot loop to exhaustion, per-thread replies, manual close-out | Adapt | Board #43; branch `v2/<type>/<N>-<slug>`. **DCO: N/A**, since no DCO app is installed here (§10). **Screenshots → client evidence**: Inspector/LLM-client transcript in both spec eras (§3.2). The Copilot loop copies unchanged | S6 |
108+
| `pr-flow` | Assign + In Progress, branch naming, DCO signoff, screenshots, `Closes #N`, `addCloseIssueReferences`, In Review, Copilot loop to exhaustion, per-thread replies, manual close-out | Adapt | Board #43; branch `v2/<type>/<N>-<slug>`. **DCO: N/A**, since no DCO app is installed here (§10). **Screenshots → client evidence**: for a server-facing change, Inspector and LLM-client transcripts in both spec eras; otherwise a targeted probe (§3.2). The Copilot loop copies unchanged | S6 |
109109
| `pre-push-gate` | Running `local:gate`; diagnosing each stage | Adapt | Rewrite around our stages: TS workspaces, Python per server, per-file coverage both sides | S10 |
110110
| `project-structure` | Where a file goes; who owns what | Adapt | Per-server layouts (e.g. `everything`'s `tools/`, `resources/`, `prompts/`, `transports/`) | S11 |
111111
| `local-dev` | Install/run each client; dependency-placement reasoning | Adapt | Workspaces + `uv`; running each server over stdio / Streamable HTTP; `npx`/`uvx` local builds | S11 |
@@ -197,12 +197,16 @@ The **Sub-issue** column points into [§9](#9-proposed-sub-issues).
197197
- **Protocol-level client harnesses, in-process**: an SDK `Client` (TS) or
198198
`ClientSession` (Py) over an in-memory transport, asserting on the wire. This
199199
is the design of #4854/#4855, and the `testing` skill (S11) documents it.
200-
- **Client smoke tests in both spec eras**, per #4857: every change is checked
201-
against a 2026-07-28 client and a 2025-11-25 client, using the Inspector V2
202-
and an LLM client. This replaces the Inspector's screenshot rule. Instead of
203-
images, a PR carries **client evidence**: what the Inspector (or an LLM
204-
client) was asked to do, and what it returned. That gives the `client-smoke`
205-
skill (S11) and the `pr-flow` evidence step (S6).
200+
- **Client smoke tests in both spec eras**, per #4857: every change to
201+
**server behavior** is checked against a 2026-07-28 client and a 2025-11-25
202+
client, using **both** the Inspector V2 and an LLM client. This replaces the
203+
Inspector's screenshot rule. Instead of images, a server-facing PR carries
204+
**client evidence**: what each client was asked to do, and what it returned.
205+
A change with no client-observable surface (docs, skills, workflows, gate
206+
tooling) instead carries a **targeted probe**, as the Inspector's ledger
207+
allows: the thing that proves it, such as a guard made to fire or a
208+
before/after run. That gives the `client-smoke` skill (S11) and the
209+
`pr-flow` evidence step (S6).
206210
- **Interface-diff CI** (#4860) gives interface-level evidence that a change
207211
is transparent. The gate sub-issue (S10) wires it in once #4860 lands.
208212

@@ -273,7 +277,7 @@ deleting. Every section goes somewhere:
273277
| MCP Protocol Reference (`.mcp.json` docs server, schema repo) | `AGENTS.md`: a two-line rule to look protocol questions up via the `mcp-docs` server, with a link to the schema repo | S1 |
274278
| Key Patterns: `registerTools`/`registerResources`/`registerPrompts` | `AGENTS.md` TS instructions (the rule). Where each server keeps them goes to `project-structure` | S1, S11 |
275279
| Key Patterns: tool annotations | `AGENTS.md` (rule: set `readOnlyHint`, `idempotentHint`, `destructiveHint` on every tool) | S1 |
276-
| Key Patterns: transports | `AGENTS.md`: stdio default, Streamable HTTP; **SSE is deprecated** (and removed by the 2026-07-28 spec, #4857) | S1 |
280+
| Key Patterns: transports | `AGENTS.md`: stdio default, Streamable HTTP; **HTTP+SSE is deprecated** (still deprecated, not removed, in the 2026-07-28 spec, #4857) | S1 |
277281
| Key Patterns: PR template checklist | `AGENTS.md` Contributing (MCP docs read, security practice, tested with an LLM client). The evidence step goes to `pr-flow` | S1, S6 |
278282

279283
`src/everything/AGENTS.md` (a per-server guide) also exists. S1 decides its
@@ -390,7 +394,7 @@ the Servers V2 board (#43). "After" means the listed issue must merge first.
390394
```
391395
W1 #4859 inception (this doc)
392396
W2 S1 AGENTS.md · S2 skills harness · S3 TS validate · S4 Py validate
393-
W3 S5 board-ops + issue-create · S6 pr-flow · S7 issue-triage · S8 contribution model · S9 security-advisory
397+
W3 S5 board-ops + issue-create · S6 pr-flow · S8 contribution model · S9 security-advisory · then S7 issue-triage (after S5, S8)
394398
W4 S10 local:gate + coverage + pre-push-gate (after S3, S4, #4854, #4855) · S11 knowledge skills
395399
W5 #4472 changesets + Release-triggered publish → S12 milestone release flow + release skill
396400
W6 S13 dependency & SDK sweeps replace Dependabot PRs
@@ -455,10 +459,12 @@ W6 S13 dependency & SDK sweeps replace Dependabot PRs
455459
**S5 (#4866). `board-ops` and `issue-create` skills; label taxonomy**
456460
- Scope: adapt both skills (§6). Create the `chore` label. Decide whether the
457461
create flow sets Size. Server-scope labels (`server-<name>`) are part of
458-
create. Board #43's IDs live **only** in `board-ops`, and option IDs are
462+
create **where the issue concerns one server** (repo-wide issues carry
463+
none). Board #43's IDs live **only** in `board-ops`, and option IDs are
459464
resolved by name.
460465
- Acceptance:
461-
- Filing an issue through the skill yields labels (`v2` + type + scope),
466+
- Filing an issue through the skill yields labels (`v2` + type, plus a
467+
scope label when one applies),
462468
milestone, card, Status and Priority, verified by a query in the PR.
463469
- Eval cases pass the threshold.
464470
- The skills index is updated.
@@ -475,7 +481,8 @@ W6 S13 dependency & SDK sweeps replace Dependabot PRs
475481
timeout) documented.
476482
- Eval cases pass the threshold.
477483

478-
**S7 (#4868). `issue-triage` skill and board audit, for community inflow**
484+
**S7 (#4868). `issue-triage` skill and board audit, for community inflow** (after
485+
S5; its outside-PR half after S8)
479486
- Scope: adapt §6. Two-pass sweep (Incoming → approval), rubric with a posted
480487
score comment, the board audit. Add triage classes for server submissions,
481488
README/`ADDITIONAL.md` listing PRs, new-server implementations, duplicate
@@ -539,17 +546,23 @@ S3, S4, #4854, #4855)
539546
### Wave 5: release
540547

541548
**#4472. changesets (TS) + GitHub-Release-triggered publishing**: folded in
542-
unchanged (§7).
549+
with its scope unchanged (§7). Its two bump PRs are why S12's preparation step
550+
is more than one PR.
543551

544552
**S12 (#4873). `v2/main` → `main` milestone release flow and `release` skill** (after
545553
#4472, S10)
546554
- Scope:
547-
- The two-PR shape: PR 1 is the audit report (npm and `uv`/pip) plus the
548-
bumps (changesets "Version Packages" for TS; the `prepare-release` CalVer
549-
stamp for Python) on `v2/main`. PR 2 is a pure `v2/main` → `main` merge
550-
whose tree hash matches `origin/v2/main`, with a release ledger artifact
551-
(`local:gate`, per-package `pack:verify`, each milestone issue exercised
552-
via `client-smoke`).
555+
- The preparation PRs, all on `v2/main`: the audit report (npm and
556+
`uv`/pip) with any fixes it forces, plus the bumps. #4472 makes the bumps
557+
**two separate PRs**, the changesets "Version Packages" PR for TS and the
558+
`prepare-release` CalVer PR for Python, so a milestone touching both
559+
ecosystems has up to three preparation PRs rather than the Inspector's
560+
one. All of them merge before the merge PR opens.
561+
- The merge PR: a pure `v2/main` → `main` merge whose tree hash matches
562+
`origin/v2/main`, with a release ledger artifact: `local:gate`,
563+
per-package `pack:verify`, each server-facing milestone issue exercised
564+
via `client-smoke`, and a targeted probe for each issue with no client
565+
surface (§3.2).
553566
- The maintainer publishes the GitHub Release.
554567
- Split `release.yml` so build and verify run without `id-token`.
555568
- The `release` skill (name-only).
@@ -570,11 +583,14 @@ unchanged (§7).
570583
`v2/main`).
571584
- Add `sdk-watch` (nightly; TS SDK packages and Python `mcp`), including the
572585
hardened analysis job's properties unchanged.
573-
- Add `verify:action-pins` for `release.yml`'s credentialed jobs.
586+
- Add `verify:action-pins` for every credentialed job: `release.yml`'s
587+
publish jobs **and** `claude.yml` (`id-token: write`, `ANTHROPIC_API_KEY`).
574588
- Add the `AGENTS.md` "dependency updates are issue-driven" rules.
575589
- Acceptance:
576590
- No Dependabot PRs open after merge.
577-
- Each sweep files a correctly labelled, milestoned issue in a dry run.
591+
- Each sweep's dry run **writes nothing** and prints the issue payload it
592+
would file, with correct labels and milestone. Live filing is exercised
593+
by script tests with a mocked `gh`, not against the real tracker.
578594
- Script tests pass.
579595

580596
## 10. Open questions for maintainers

0 commit comments

Comments
 (0)