You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Part of the agentic software factory tracker #4858.
What this adds
docs/agent-guidance-inception.md inventories the MCP Inspector's agentic software factory and decides how each part carries over to this repo. Sources: inspector#2498 and the Inspector's v2/main at 64a50d6f.
§2 Inventory and verdicts. Every element gets a verdict of Transfer, Adapt or N/A, with the adaptation or reason. Covered: each AGENTS.md rule group, all 11 skills, every gate script, the CI and release workflows, the three automated sweeps, and board, label and milestone conventions.
§3 What only this repo needs:
two-language, per-package gates, with a Python equivalent for every TS gate
server-oriented testing with in-process protocol harnesses and client smoke tests in both spec eras
two-registry, per-package release
triage for heavy community inflow
advisories for servers with filesystem, git and network reach
§4 Retiring CLAUDE.md. Every section maps to an AGENTS.md rule, a skill, or is dropped as derivable. CLAUDE.md gets deleted outright, with no pointer file.
61 advisories are in triage, while SECURITY.md says the repo isn't eligible for reports.
ruff isn't run in CI.
There's no chore label and there are no issue forms.
§9 Proposed sub-issues. S1–S13 in Waves 2–6, each with a scope and acceptance criteria.
§10 Open questions for maintainers:
whether to keep accepting outside PRs
whether to adopt DCO
coverage enforcement in CI
the Size field
milestones for the later waves
How this was tested
This is a docs-only change. Every repo fact was checked against live state with gh and git: labels, milestones, board #43 fields, repository and security settings, workflows, and per-server tooling.
Inventory the MCP Inspector's agentic software factory (AGENTS.md rules,
skills, gate scripts, CI and release workflows, board conventions), give each
element a transfer/adapt/N/A verdict for this repo, map every CLAUDE.md
section and #4473 decision to a destination, list reusable templates, and
propose the wave-ordered sub-issues of #4858.
Closes#4859
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
Copilot review, round 1: 8 findings, all fixed in 306380c. Each thread has its own reply. The sub-issues they touch (#4867, #4873, #4874) were updated to match.
Action pinning now covers claude.yml as well as release.yml.
Client evidence is scoped to server-facing changes (both clients, both eras). Everything else carries a targeted probe.
Scope labels apply only where an issue concerns one server.
Open decision is outside the three verdicts defined above and does not satisfy #4859's requirement to classify every Inspector element as Transfer, Adapt, or N/A. This rule is still an adaptation whose final policy is deferred to S8.
This issue also appears in the following locations of the same file:
- Contributing is Adapt, with the policy deferred to S8; qualifiers such
as 'inverted' and 'later' move out of the verdict column
- Size is not an Inspector element, so it moves out of the inventory table
- S6 after S5; S10 also after S2; S12 also after S11 (client-smoke)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot review, round 2: no inline comments, and one finding in "Previously missed" (no thread to reply to, so answered here). Fixed in 0df4677.
"Replace Open decision with a defined verdict" (line 82, and the same class elsewhere). Fixed. The Contributing row is now Adapt, with the policy itself deferred to the S8 maintainer decision. Every verdict column now uses only Transfer, Adapt or N/A: qualifiers such as "inverted", "later", "mostly" and "for now" moved into the reason column. The Size-field row wasn't an Inspector element, so it now sits below the table as a this-repo-only note.
The overview's "several incorrect dependency relationships" had no specific finding attached. A re-check turned up three, all fixed:
S6 (pr-flow) now depends on S5, whose board-ops it uses.
S10 (local:gate) now also depends on S2, for verify:skills:cli.
S12 (release) now also depends on S11, because the ledger uses client-smoke.
Shared dependency version guard remains unenforced
docs/agent-guidance-inception.md:133
A single npm lockfile can still resolve multiple versions for different workspaces. The current manifests already declare different TypeScript ranges (everything uses ^5.6.2, filesystem uses ^5.8.2, and sequentialthinking uses ^5.3.3), so marking this guard N/A leaves the “one version of a shared devDependency” rule on line 78 unenforced.
This issue also appears on line 134 of the same file.
Root guards are missing from CI matrix jobs
docs/agent-guidance-inception.md:444
The adapted root guards are only included in the root aggregate, while every described CI matrix leg runs the package-only validate. Without a dedicated root guard job, verify:format-coverage, verify:typecheck-coverage, and formatting/lint failures in root files are not actually CI-gated.
This issue also appears on line 453 of the same file.
Dependabot backlog is not addressed
docs/agent-guidance-inception.md:602
Six Dependabot PRs are currently open, but this scope only disables future PR creation and does not close the backlog. The created #4874 therefore uses “No new Dependabot PRs open after merge”; this stronger criterion is not satisfied by the described work and no longer matches the sub-issue.
Misstates Inspector guidance on paths
docs/agent-guidance-inception.md:87
The Inspector rule does not ban paths; it says to use them only when a skill is useless outside the matched files and to document the tradeoff. Calling this a direct transfer while summarizing it as “no paths” misstates the source and would make S2 unnecessarily stricter.
…log, paths rule
- S3 adds a root-guards CI job for checks no package leg covers
- verify:dep-lockstep is Adapt: one range per shared TS devDependency
- S13 works down the six open Dependabot PRs
- The skills rule allows paths with a stated trade-off, as the Inspector does
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot review, round 5: no inline comments, and four findings in "Previously missed". All fixed in 93b83d3.
The shared-dependency version guard was marked N/A. Fixed. verify:dep-lockstep is now Adapt: a smaller guard requiring one range for each shared TS devDependency, or hoisting it to the root (today typescript alone has three ranges). It runs in S3's root-guards job. verify:install-fresh stays N/A, because npm ci already fails on a lockfile mismatch.
Root guards were missing from the CI matrix. Fixed. S3 adds a separate root-guards CI job for root-file format/lint, verify:format-coverage, verify:typecheck-coverage and the version guard.
The Dependabot backlog wasn't addressed. Fixed. S13 now works down the six open Dependabot PRs, converting each still-needed bump to an issue and closing the PR with a pointer. There are separate acceptance criteria for "no new PRs" and "backlog closed".
The Inspector's paths guidance was misstated. Fixed. The rule is now "paths only when a skill is useless outside the matched files, with the trade-off stated", matching the source.
#4863, #4864 and #4874 are updated to match. Requesting round 6.
File purpose-header requirement is not separately addressed
docs/agent-guidance-inception.md:76
This row combines the annotated-tree rule with the Inspector's separate requirement that every file have a purpose/rationale header, but the adaptation only addresses the tree. Existing source files such as src/filesystem/index.ts and src/time/src/mcp_server_time/server.py do not follow that header convention, so S1 cannot tell whether to introduce a repository-wide requirement or omit it. Give the header rule its own verdict and either scope the migration or mark it N/A with a reason.
Workflow gate script and tests are missing from coverage
docs/agent-guidance-inception.md:122
The pinned Inspector revision also has scripts/lib/workflow-gate.mjs and its tests. That guard enforces the local-vs-CI split and ensures local:gate remains exactly the lease wrapper, but it is absent from the inventory, reusable templates, and S10 even though #4859 requires every gate script to be covered. Add an Adapt/N/A verdict and carry any applicable invariants into S10/#4871.
Empty skills directory breaks the ported verifier
docs/agent-guidance-inception.md:429
The verifier being ported deliberately fails when .claude/skills/ is empty (no skills found; the skill set is gone). Requiring the default command to pass empty either contradicts the port or permanently removes protection against deleting every skill. Seed S2 with at least one real skill, or define an explicitly temporary bootstrap mode and require its removal when the first skill lands.
Incorrectly claims every server has a package.json
docs/agent-guidance-inception.md:78
The repository has only four package.json files under src/; the three Python servers use pyproject.toml. Saying every server has its own package.json makes the N/A rationale factually incorrect. Limit this statement to TypeScript servers while retaining the independent-publication point.
…e pin scope
- The per-file purpose header gets its own row: Adapt, with no bulk
migration
- package.json applies to the four TS servers only
- workflow-gate.mjs is inventoried (Adapt, S10) and listed as a template
- S2 keeps the verifier's no-skills failure, behind a temporary bootstrap
allowance that the first skill PR removes
- Action pinning covers jobs whose artifacts credentialed jobs download
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Issue-reference rule conflicts with issue-less Dependabot PRs
docs/agent-guidance-inception.md:85
Assigning the unconditional “every PR references an issue” rule to S1 conflicts with the current automation documented in §8: Dependabot continues opening issue-less PRs until S13. That also violates S1's requirement that every rule be true when it merges. Either defer this rule to S13 or make the existing automated dependency PRs an explicit temporary exception that S13 removes.
Python validation omits the required package build step
docs/agent-guidance-inception.md:471
The planned Python validate omits package building, but python.yml currently gates every package with uv build after pyright. Since S10 only chains this validate yet promises to run every CI check, the local gate could pass while CI fails to build a wheel. Include uv build in each per-server validation (or add an explicit Python build stage to S10).
- S1 states 'every PR references an issue' with an explicit temporary
exception for Dependabot PRs, which S13 removes
- S4's per-server validate includes uv build, which CI already gates
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🔵 Needs a closer look
The roadmap contains inconsistent dependencies and first-skill bootstrap responsibilities that could leave planned acceptance criteria unsatisfied.
Review effort: Balanced Findings: None
Previously missed (3)
In code that hasn't changed since last review
Add S1 dependency or handoff rule for S3 and S4
docs/agent-guidance-inception.md:407
Wave 2 is declared parallel, but S3 and S4 both require edits to the root AGENTS.md that S1 creates, while neither has an S1 dependency or S2's explicit handoff fallback. If either lands first, it must either create/overlap S1's file or omit part of its scope. Add an S1 dependency or the same handoff rule to S3/S4, and synchronize #4864/#4865.
Include S10 and S11 in empty-skills bootstrap removal
docs/agent-guidance-inception.md:435
This candidate list omits S10 and S11, both of which add skills and are allowed by their declared dependencies to run after S2 without waiting for S5 or S9. If either lands first, the empty-skills bootstrap remains and deleting every skill can still pass verification. Make every potentially first skill PR (S5, S9, S10, and S11) responsible for removing it, and update #4863/#4871/#4872 accordingly.
This issue also appears on line 480 of the same file.
Align S11 regression requirement with available skills
docs/agent-guidance-inception.md:575
S11 only depends on S2, so it may run before the Wave 3 skills exist; requiring a regression run specifically against those skills is then unsatisfiable. Match #4872's acceptance criterion by saying “skills that already exist,” or add explicit Wave 3 dependencies.
…moval
- S3 and S4 hand their AGENTS.md rules to S1 if it hasn't merged yet
- Whichever skill-adding issue lands first (S5, S6, S9, S10 or S11)
removes S2's empty-skills bootstrap allowance
- S11's regression check targets the skills that already exist
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Finalize the factory overview after Wave 6 automation
docs/agent-guidance-inception.md:606
This “closing” factory document is scheduled in Wave 5, but Wave 6 still adds the dependency/security sweeps, SDK watch, action-pin guard, and final AGENTS.md rule changes. Publishing the overview in S12 will therefore describe an incomplete factory and become stale immediately. Move this task to S13, or explicitly require S13 to finalize/update it after automation lands.
- Action pinning, including the jobs that produce artifacts credentialed
jobs consume, lands with the release split, before the first milestone
release
- The closing docs/ai-software-factory.md is written in S13, after Wave 6
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot review loop closed: round 10 was clean. It had no inline comments and nothing in "Previously missed", and the overview reads "🟢 Approval recommended". Rounds 1–9 raised 29 findings in total. All were fixed, and the affected sub-issues (#4862–#4874) and the #4858 tracker were kept in sync. The PR is ready for maintainer review.
This branch has not been deployed
No deployments
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #4859
Part of the agentic software factory tracker #4858.
What this adds
docs/agent-guidance-inception.mdinventories the MCP Inspector's agentic software factory and decides how each part carries over to this repo. Sources: inspector#2498 and the Inspector'sv2/mainat64a50d6f.AGENTS.mdrule group, all 11 skills, every gate script, the CI and release workflows, the three automated sweeps, and board, label and milestone conventions.CLAUDE.md. Every section maps to anAGENTS.mdrule, a skill, or is dropped as derivable.CLAUDE.mdgets deleted outright, with no pointer file.board-opsskill, with IDs resolved by name at run time.SECURITY.mdsays the repo isn't eligible for reports.chorelabel and there are no issue forms.How this was tested
This is a docs-only change. Every repo fact was checked against live state with
ghand git: labels, milestones, board #43 fields, repository and security settings, workflows, and per-server tooling.🤖 Generated with Claude Code