Tracker: Agentic software factory (AGENTS.md, skills, quality gates, v2/main release flow) #4858

Goal

Stand up an agentic software factory for this repo, modeled on the MCP Inspector's (see inspector#2498, "MCP Inspector: Our AI Software Factory"). The target is robust, exhaustively tested, regression-free code pushed every time, with CI validating it before merge.

Target shape

• AGENTS.md holds the absolute rules: short, always loaded, and true on the day they're stated. There is no CLAUDE.md, because Claude Code reads AGENTS.md directly. Everything useful in today's CLAUDE.md moves into AGENTS.md or a skill (Inception — inventory the Inspector factory, write docs/agent-guidance-inception.md #4859).

• .claude/skills/ holds skills that load only when needed, covering at least:

  • issue creation
  • PR flow
  • board operations (Servers V2 board, Initial GitLab server version #43)
  • the quality gates (pre-push/local gate, per-file coverage, lint/typecheck)

  The inspector's current skill set is a starting point: board-ops, issue-create, issue-triage, local-dev, pr-flow, pre-push-gate, project-structure, release, security-advisory, test-servers, testing.

• CI enforces the gates before merge. A green PR has passed the same checks the agent ran locally.

• Branching: development happens on v2/main, which is merged to main in milestone releases, each with its own publish steps.

How this repo differs from the Inspector

The Inspector is the model, but not a template to copy wholesale:

• Many packages, not one app. This repo is a monorepo of seven independently published servers, not a single client application. Rules and gates must work per package and across the workspace.

• Two languages and two registries:

  • TypeScript: npm workspaces, vitest, tsc; published to npm.
  • Python: uv, pytest, pyright, ruff; published to PyPI.

  Each needs equivalent gates, skills and release steps.

• Servers, not clients. Testing leans on protocol-level client harnesses and LLM-client smoke tests rather than UI or TUI smoke tests.

• Community-heavy inflow. This repo receives many drive-by issues and PRs, including server-submission spam, so triage matters more here.

Sub-issues

#4463

Wave 1: inception

• New release pipeline, Phase 1: OIDC trusted publishing #4463
• Inception — inventory the Inspector factory, write docs/agent-guidance-inception.md #4859 Part 1: Inventory the Inspector's factory and write docs/agent-guidance-inception.md

The waves come from the inception doc, docs/agent-guidance-inception.md §9 (PR #4861).

Wave 2: rules and scaffolding (parallel, except #4864 after #4863)

• AGENTS.md: the absolute rules; delete CLAUDE.md #4862 Part 2: AGENTS.md (the absolute rules); delete CLAUDE.md
• Skills infrastructure: .claude/skills/, verify:skills, skills:eval #4863 Part 3: Skills infrastructure (.claude/skills/, verify:skills, skills:eval)
• TypeScript workspace gate: Prettier, ESLint, root validate, CI #4864 Part 4: TypeScript workspace gate (Prettier, ESLint, root validate, CI) (after Skills infrastructure: .claude/skills/, verify:skills, skills:eval #4863)
• Python gate parity: ruff, ruff format, pyright, pytest in one command and in CI #4865 Part 5: Python gate parity (ruff, ruff format, pyright, pytest; in CI)

Wave 3: work-tracking and security skills (after #4862, #4863)

• Board-ops and issue-create skills; label taxonomy #4866 Part 6: board-ops and issue-create skills; label taxonomy
• Add pr-flow skill #4867 Part 7: pr-flow skill (after Board-ops and issue-create skills; label taxonomy #4866)
• Add issue-triage skill and board audit, for community inflow #4868 Part 8: issue-triage skill and board audit, for community inflow (after Board-ops and issue-create skills; label taxonomy #4866, Contribution model: outside PRs, CONTRIBUTING.md, PR template, issue forms #4869)
• Contribution model: outside PRs, CONTRIBUTING.md, PR template, issue forms #4869 Part 9: Contribution model (outside PRs, CONTRIBUTING.md, templates, issue forms). Needs a maintainer decision
• Add security-advisory skill; reconcile SECURITY.md with the advisory backlog #4870 Part 10: security-advisory skill; reconcile SECURITY.md with the advisory backlog (after Board-ops and issue-create skills; label taxonomy #4866)

Wave 4: quality gate and knowledge skills

• Add local:gate, pre-push-gate skill #4871 Part 11: local:gate, pre-push-gate skill (after Skills infrastructure: .claude/skills/, verify:skills, skills:eval #4863, TypeScript workspace gate: Prettier, ESLint, root validate, CI #4864, Python gate parity: ruff, ruff format, pyright, pytest in one command and in CI #4865). Per-file coverage moved out to Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854 and Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855, so this no longer waits on the spec refactor
• Knowledge skills: project-structure, local-dev, testing, client-smoke #4872 Part 12: Knowledge skills: project-structure, local-dev, testing, client-smoke

Wave 5: release

• New release pipeline, Phase 2: semver via changesets (TS), GitHub-Release-triggered publishing #4472 Part 13: v2 release pipeline Phase 2: changesets (TS) + GitHub-Release-triggered publishing (folded in)
• v2/main → main milestone release flow and release skill #4873 Part 14: v2/main → main milestone release flow and release skill (after New release pipeline, Phase 2: semver via changesets (TS), GitHub-Release-triggered publishing #4472, Board-ops and issue-create skills; label taxonomy #4866, Add local:gate, pre-push-gate skill #4871, Knowledge skills: project-structure, local-dev, testing, client-smoke #4872)
• First semver release: TypeScript servers at 1.0.0 and Python servers at the next CalVer, the frozen legacy-era servers #4968 Follow-up: first semver release (deprecate the date-stamped npm versions; release one milestone end to end through the release skill)

Wave 6: automation

• Replace Dependabot PRs with issue-filing sweeps; SDK watch; the factory overview #4874 Part 15: Replace Dependabot PRs with issue-filing sweeps; SDK watch; the factory overview (after Board-ops and issue-create skills; label taxonomy #4866, v2/main → main milestone release flow and release skill #4873)

Existing issues to reconcile

The inception doc (§7) decided each of these. (#4473, the AGENTS.md adoption plan, was already folded into #4859.)

• New release pipeline, Phase 2: semver via changesets (TS), GitHub-Release-triggered publishing #4472 (v2 release pipeline Phase 2: semver via changesets (TS), publishing triggered by GitHub Releases): folded in as a Wave 5 sub-issue, with its scope unchanged. v2/main → main milestone release flow and release skill #4873 builds the milestone-merge half on top of it.
• Tracker: 2026-07-28 Spec Refactor #4857 (2026-07-28 Spec Refactor tracker): unchanged. Its Parts 1–2 (Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854, Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855) stay there and own per-file 90% coverage end to end: the suites, the thresholds, the parallel CI coverage job, the coverage stage in local:gate, and their language's half of the AGENTS.md coverage rule. The factory's Add local:gate, pre-push-gate skill #4871 builds local:gate without coverage and does not wait on them (the earlier plan had Add local:gate, pre-push-gate skill #4871 do the wiring, which put the whole gate behind the spec refactor). One correction was fed back: the Inspector now enforces coverage in CI (inspector#2159), so they do the same.
• Set up eslint and prettify #197 (set up eslint and prettier): superseded by TypeScript workspace gate: Prettier, ESLint, root validate, CI #4864.

Branch

As with the spec refactor, PRs target v2/main. Closes #N won't auto-close issues on a non-default branch, so close them by hand on merge and move the card to Done.