feat(skills): publish objectstack-pm-dispatch — the project-agnostic PM dispatch loop (#4607) (#4621)

Generalizes the repo-internal .claude/skills/pm-dispatch core into the
published skills/ catalog so any ObjectStack project (hotcrm, customer
projects) can install the loop with the skills CLI.

Project-specific rules are replaced by two seams: an optional
.claude/pm-dispatch.json (backlogRepo / repos / batch / mode /
conventionsFile / routingLabelPrefix, zero-config = current repo is the
only shard and the backlog), and pointers to the project's own conventions
file for gates, release-note artifacts, branch naming and merge policy.

The developer-agent procedure ships embedded as a paste-in template, so the
loop needs no custom agent types. Adds the upstream-reporting section for
platform defects found in an app project. The internal .claude version is
untouched.


Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/published-pm-dispatch-skill.md

@@ -0,0 +1,40 @@
+---
+---
+
+docs(skills): publish `objectstack-pm-dispatch` — the project-agnostic core of the PM dispatch loop, installable by any ObjectStack project (#4607).
+
+The multi-agent delivery loop (backlog triage → claim → dispatch → structured
+report → review → land) has only existed as repo-internal agent tooling under
+`.claude/`. Third-party projects building on ObjectStack — hotcrm, customer
+projects — run the same shape of work and had nothing to install. This adds the
+generalized skill to the published `skills/` catalog:
+
+- **Config over hardcoding.** The loop reads an optional
+  `.claude/pm-dispatch.json` (`backlogRepo`, `repos`, `batch`, `mode`,
+  `conventionsFile`, `routingLabelPrefix`); with no file the current repository
+  is both the only shard and the backlog. Every project-specific gate — branch
+  naming, release-note artifact, test commands, merge policy — is read from the
+  project's own conventions file rather than baked into the skill, and that file
+  wins on conflict.
+- **The developer-agent operating procedure is embedded as a template** the PM
+  pastes into each dispatch, so the loop works with no custom agent types:
+  worktree-first, scope = the issue, contract-first (no lenient consumer
+  fallback), the JSON report contract, `needs_decision` instead of guessing, and
+  the container resource discipline (shared heavy-verify `flock`, heap cap,
+  scoped builds, PID-only process operations, worktree cleanup).
+- **The two-axis decision frame is kept verbatim** because both axes generalize:
+  ① long-term architectural soundness for this project, ② making AI-authored
+  code — especially AI-authored metadata — structurally hard to get wrong
+  (tighten the producer, never make the consumer tolerant).
+- **New: upstream reporting.** What an app project does when it finds a
+  *platform* defect — stale-premise check against upstream first, minimal repro
+  with pinned versions and the contract being cited, **never** a tolerant
+  workaround in the app, an upstream issue backlinked with `Part of <app>#N` and
+  carrying none of the upstream's queue labels, and the app-side task parked as
+  `Blocked-by:` or as a version pin with a written unblock condition.
+
+Catalog registration only — `metadata.domain: process`, no `metadata.internal`,
+listed in `skills/README.md` and `content/docs/ai/skills-reference.mdx` via the
+existing `build-skill-docs.ts` generator. The repo-internal `.claude` version is
+untouched. Releases nothing: no published package's shipped files change
+(`packages/spec` does not ship `scripts/`).

content/docs/ai/skills-reference.mdx

@@ -5,7 +5,7 @@ description: Reference for every ObjectStack AI skill — domain-scoped knowledg
 
 # AI Skills Reference
 
-ObjectStack ships a set of **domain-specific skills** that teach AI assistants (Claude Code, GitHub Copilot, Cursor, …) the protocol's schemas, patterns, and constraints. This guide is the complete catalog.
+ObjectStack ships a set of **domain-specific skills** that teach AI assistants (Claude Code, GitHub Copilot, Cursor, …) the protocol's schemas, patterns, and constraints — plus **process** skills that teach how work moves through a project rather than what to author. This guide is the complete catalog.
 
 <Callout type="info">
 **New to skills?** Read [AI Skills System](/docs/ai/skills) first for the conceptual overview, then return here for the per-skill reference.
@@ -39,7 +39,7 @@ Skills are versioned as **one bundle**. You do not track or update each skill in
 
 {/* BEGIN GENERATED: skills (packages/spec/scripts/build-skill-docs.ts) — DO NOT EDIT */}
 
-ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI assistant loads only the ones a task needs.
+ObjectStack ships **10 skills** — one per authoring domain, plus process skills for how a project is delivered. Each is self-contained: an AI assistant loads only the ones a task needs.
 
 ## Quick Reference
 
@@ -54,6 +54,7 @@ ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI
 | 7 | [API](#api) | `api` | `skills/objectstack-api/` | Design the server-side API surface that an ObjectStack runtime exposes — REST endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. |
 | 8 | [i18n](#i18n) | `i18n` | `skills/objectstack-i18n/` | Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. |
 | 9 | [Formula](#formula) | `expression` | `skills/objectstack-formula/` | Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. |
+| 10 | [PM Dispatch](#pm-dispatch) | `process` | `skills/objectstack-pm-dispatch/` | Run a project-manager dispatch loop over a GitHub backlog: triage and queue ready issues, claim each one, dispatch it to a parallel developer agent that returns a structured JSON report, review the results against GitHub, and drive accepted pull requests to landing — escalating to the maintainer only what genuinely needs a human decision. Ships the developer-agent operating template the loop injects into every dispatch (no custom agent types required) and the upstream-reporting procedure for platform defects an app project finds. |
 
 ---
 
@@ -183,6 +184,20 @@ Do not use for SQL fragments (driver-native), cron schedules (cron dialect), or
 
 ---
 
+### PM Dispatch
+
+**Domain** `process` · **Path** `skills/objectstack-pm-dispatch/`
+
+Run a project-manager dispatch loop over a GitHub backlog: triage and queue ready issues, claim each one, dispatch it to a parallel developer agent that returns a structured JSON report, review the results against GitHub, and drive accepted pull requests to landing — escalating to the maintainer only what genuinely needs a human decision. Ships the developer-agent operating template the loop injects into every dispatch (no custom agent types required) and the upstream-reporting procedure for platform defects an app project finds.
+
+Use when asked to "work through the backlog", "batch-dispatch issues", "派发 issue 给开发 agent", to stand up a multi-agent delivery loop in an ObjectStack app project, or to report a platform bug found while building an app.
+
+Do not use for authoring ObjectStack metadata (the domain skills cover that), for a single already-scoped change you can just make, or as a replacement for the project's own conventions file — that file always wins.
+
+**Tags:** `pm`, `dispatch`, `backlog`, `triage`, `multi-agent`, `delivery`, `github`, `escalation`, `upstream`
+
+---
+
 {/* END GENERATED: skills */}
 
 ## Skill anatomy

content/docs/ai/skills.mdx

@@ -128,7 +128,7 @@ This format ensures AI assistants generate protocol-compliant code.
 
 ## The skill catalog
 
-ObjectStack provides **nine domain-specific skills**, one per protocol domain — Platform, Data, Query, UI, Automation, AI, API, i18n, and Formula.
+ObjectStack provides **nine domain-specific skills**, one per protocol domain — Platform, Data, Query, UI, Automation, AI, API, i18n, and Formula — plus **PM Dispatch**, a `process` skill that teaches no schema: it runs the multi-agent backlog → dispatch → review → land loop for a project built on the platform, and the procedure for reporting a platform defect upstream.
 
 The authoritative list (names, domains, and "use when / do not use" boundaries) is generated from each skill's `SKILL.md` frontmatter. See the **[AI Skills Reference](/docs/ai/skills-reference)** for the full catalog with per-skill detail.
 

packages/spec/scripts/build-skill-docs.ts

@@ -54,6 +54,7 @@ const DISPLAY: Array<{ name: string; label: string }> = [
   { name: 'objectstack-api', label: 'API' },
   { name: 'objectstack-i18n', label: 'i18n' },
   { name: 'objectstack-formula', label: 'Formula' },
+  { name: 'objectstack-pm-dispatch', label: 'PM Dispatch' },
 ];
 
 // ── Frontmatter parser ───────────────────────────────────────────────────────
@@ -178,7 +179,7 @@ function renderGuideBlock(skills: Skill[]): string {
   return [
     begin,
     '',
-    `ObjectStack ships **${skills.length} domain-specific skills**. Each is self-contained — an AI assistant loads only the ones a task needs.`,
+    `ObjectStack ships **${skills.length} skills** — one per authoring domain, plus process skills for how a project is delivered. Each is self-contained: an AI assistant loads only the ones a task needs.`,
     '',
     '## Quick Reference',
     '',

skills/README.md

@@ -12,7 +12,7 @@ npx skills add objectstack-ai/objectstack/skills --all
 The `/skills` subpath matters: it is the published catalog boundary — pointing
 the skills CLI at the repo root would also pick up repo-internal skills (#3101).
 
-Each skill is self-contained: a `SKILL.md` with YAML frontmatter, plus a
+Each **domain** skill is self-contained: a `SKILL.md` with YAML frontmatter, plus a
 `references/_index.md` that points into the authoritative Zod sources in
 `node_modules/@objectstack/spec/src/...` (the published `@objectstack/spec`
 package ships these `.zod.ts` sources, so the pointers resolve in consumer
@@ -38,6 +38,7 @@ apps too).
 | [API](./objectstack-api/SKILL.md) | `api` | Design the server-side API surface that an ObjectStack runtime exposes — REST endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. |
 | [i18n](./objectstack-i18n/SKILL.md) | `i18n` | Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. |
 | [Formula](./objectstack-formula/SKILL.md) | `expression` | Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. |
+| [PM Dispatch](./objectstack-pm-dispatch/SKILL.md) | `process` | Run a project-manager dispatch loop over a GitHub backlog: triage and queue ready issues, claim each one, dispatch it to a parallel developer agent that returns a structured JSON report, review the results against GitHub, and drive accepted pull requests to landing — escalating to the maintainer only what genuinely needs a human decision. Ships the developer-agent operating template the loop injects into every dispatch (no custom agent types required) and the upstream-reporting procedure for platform defects an app project finds. |
 
 <!-- END GENERATED: skills -->
 
@@ -59,15 +60,19 @@ skills/<skill-name>/
                           # inert (but harmless) in consumer installs
 ```
 
+A `process` skill (`metadata.domain: process`) points at no Zod schema, so it
+carries `SKILL.md` alone — `gen:skill-refs` only visits skills listed in its
+`SKILL_MAP`, and there is nothing to map.
+
 `SKILL.md` frontmatter fields:
 
 | Field | Purpose |
 |:------|:--------|
 | `name` | Stable id (matches directory name). |
 | `description` | One paragraph — what the skill is for *and* what it is **not** for. |
 | `license` | `Apache-2.0`. |
-| `compatibility` | Minimum `@objectstack/spec` version. |
-| `metadata.domain` | One of: `platform`, `data`, `query`, `ui`, `automation`, `ai`, `api`, `i18n`, `formula`. |
+| `compatibility` | Minimum `@objectstack/spec` version — or, for a `process` skill that binds to no schema, the tooling it needs. |
+| `metadata.domain` | Authoring domain — one of: `platform`, `data`, `query`, `ui`, `automation`, `ai`, `api`, `i18n`, `expression` — or `process` for a delivery-process skill that teaches no schema. |
 | `metadata.tags` | Short comma-separated keywords for retrieval. |
 
 ---