pm-sync-core
The canonical product-sync mechanism — stage, draft and file a product change for maintainer approval, and the lifecycle sync that moves one spec's backlog cards to specced, implementing or shipped with a decision entry
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- pm-sync-core
- description
- The canonical product-sync mechanism — stage, draft and file a product change for maintainer approval, and the lifecycle sync that moves one spec's backlog cards to specced, implementing or shipped with a decision entry
- argument-hint
- <spec-name> --to specced|implementing|shipped [--premise "<verdict line>"]
03 SKILL.md 正文
PM Sync Core
Two things live here, and every product skill uses the first:
- §File a change: how any change to
product/is drafted, validated and filed for a maintainer's approval. It is the single place that procedure is written down. - §Lifecycle sync: the mechanical status transition for one spec's cards when the spec lifecycle moves:
/create-specand/specsync tospecced,run-spectoimplementing,finalize-spectoshipped.
Agents never write product/ directly. .claude/hooks/guard-product-write.sh releases a write only against a maintainer's signed approval of that exact change (product/README.md, .claude/rules/product-management.md).
Input
$ARGUMENTS for the lifecycle sync: the spec name, --to <status>, and for specced an optional --premise "<line>" recording the grounding verdicts on the card. Other skills call §File a change with their own drafts.
Invocation contexts
- Slash command: runs the sync, files the requests and prints the maintainer's approve commands.
- Model-invoked: the same; a calling skill's run continues after the requests are filed.
- Non-interactive: the same. Filing a request writes only to
orchestration/requests/, never toproduct/, so it needs no pre-approval; the product write waits for the maintainer's signature in every context. A step that needs a decision the algorithm does not encode is an escalation: stop and report it.
File a change
- Stage.
STAGE="$(mktemp -d)"; python3 scripts/pm/pm.py stage "$STAGE". This copies the product files, including the README; nothing underproduct/changes. Use a fresh directory: any existing destination file or link is rejected before copying. - Draft. Run each
pm.pywrite verb against the stage:python3 scripts/pm/pm.py --product-dir "$STAGE" <verb> ... --out "$STAGE/<file>". Chain as many as the change needs; each reads the staged files and writes one back. For reviewed prose usedraft-text objectives|readme|backlog-preamble --from <scratch-source> --out <staged-file>; it never writes product files or changes card/log records. A new card or entry id comes from the verb itself, which reserves it withpm.py next-idat this moment; never type an id you remember, and never put a number in a draft you show before this step. - Record the decision. Every change except a pure roadmap redraft appends a
decisions.mdentry withpm.py ... decide --type <type>, naming the cards and the evidence. - Redraft the roadmap when a card's status or score changed:
pm.py --product-dir "$STAGE" roadmap --out "$STAGE/roadmap.md". - Validate the whole staged set:
python3 scripts/pm/pm.py --product-dir "$STAGE" validatemust printproduct: OK(a stale-roadmap warning means step 4 was skipped). The verbs refuse a draft that would not validate, so a failure here is a finding to fix, not to file. - Check the diff is proportional:
diff -u product/<file> "$STAGE/<file>"for each file. A status flip is a few lines; if unrelated cards moved or changed, stop and find out why before filing. - File one request per changed file, ids
<slug>-<file stem>:python3 scripts/orchestration/approvals.py request <slug>-backlog --path product/backlog.md --proposed "$STAGE/backlog.md" --summary "<what and why>". Exception, a lifecycle sync under the maintainer's autonomy grant: whenpython3 scripts/orchestration/autonomy.py pm-sync-check --path product/<file> --proposed "$STAGE/<file>"printspre-approved, write that file with the Write tool instead of filing it (backlog first, then decisions, then roadmap, since the roadmap check regenerates from the written backlog), and skip step 8 for it.guard-product-write.shreleases exactly those writes and records them. A file it refuses is filed as above. - Hand off. Report the request ids and the maintainer's commands:
scripts/orchestration/approve.sh show <id>, thenapprove <id> --apply(writes the file) orreject <id>. Continue with independent work; never wait by polling. - Apply, if asked. When the maintainer approved without
--apply, write each file with the Write tool using exactly the content oforchestration/requests/<id>/proposedin the main checkout. A block saying the approval is stale means the file changed since the request: restage and refile from step 1; never adapt the old draft by hand. - Commit the applied files by name (
git commit -s -m "<msg>" -- product/<file> ...) on a branch, and open or update a pull request.
Lifecycle sync
Zero-judgment bookkeeping. A dispatcher may hand it to harness-clerk, passing no effort parameter (knowledge/agent-routing.md).
- Resolve the spec with
scripts/harness/spec-lifecycle.sh resolve <spec-name>. - Find its cards, as a set: every
- **Backlog card**: MH-<n>line in the spec'srequirements.md(or inplan.mdfor an epic), plus every card whose Spec field names the spec (python3 scripts/pm/pm.py list --jsonand read thespecfield). No card: reportPM sync: skipped (no card names <spec-name>)and stop. Never invent a link. - Skip what is already there, per card:
speccedskips a card alreadyspecced,implementingorshipped;implementingskipsimplementingorshipped;shippedskipsshipped. Adroppedcard is an escalation: a spec is moving for work the backlog says will not be done. - Stage (§File a change step 1) and, for each remaining card, draft in the stage:
specced:set-status MH-<n> specced --spec <spec-name>(the Spec field keeps any other specs it names; pass them all, comma-separated). With--premise, alsoset MH-<n> premise-grounded "<line>".implementing:set-status MH-<n> implementing.shipped:set-status MH-<n> shipped. When the card names another spec that is not yet indone/orarchived/, pm.py refuses and exits 1. Then the card staysimplementing: draftset MH-<n> half-shipped "<spec-name> shipped in <PR link>; the card ships with <remaining specs>"instead and report it as held.
- Decision entries, one per changed card:
decide --type lifecycle-sync --title "MH-<n> → <status> (<spec-name>)" --decision "<card> moved to <status>" --rationale "<spec-name> reached <spec state>" --cards MH-<n>with--evidencenaming the pull request or CI run when there is one. - Roadmap, validate, file and hand off: §File a change steps 4 to 8, request slug
sync-<spec-name>-<status>. - Report, one line per card found in step 2, so the count can be checked against the set:
PM sync: MH-<n> → <status> (requests <ids>),PM sync: MH-<n> skipped (already <status>)orPM sync: MH-<n> held at implementing (half shipped; waits for <specs>). After ashippedsync, add:Consider /impact-review once the change has been in use.
Output
PM sync: <one line per card>
Requests: <ids>, for the maintainer: scripts/orchestration/approve.sh show <id> && scripts/orchestration/approve.sh approve <id> --apply
04 同仓库更多 Skills
mythhelm-deliver-backlog
Coordinate a MYTHHELM backlog run with the shared stage checks and maintainer checkpoints.
mythhelm-bootstrap
Orient a Grok Build session in the MYTHHELM repository before task or spec work.
vendor-consult
Run one advisory stage consult (premise-ground, spec-validate, task-review, change-review, stuck-oracle, dossier) with an optional external vendor, then adjudicate the answer at its anchors
update-docs
Bring README, docs/, knowledge/, WORKFLOW.md and CLAUDE.md in line with what a shipped spec or a merged change actually did — find every statement the change made stale, fix it where readers look, and add only the new facts they need
triage
Score an idea or a GitHub issue against the master spec's stages, gates and commitments, check it for duplicates, and recommend whether it becomes a backlog card; read-only
test-driven-development
Red-green-refactor for Go — use when implementing any feature, bug fix or behaviour change, before writing implementation code