Edit on GitHub

Onboarding

Use this guide to become productive in your first two hours without breaking release flow or tracker integrity.

Agent Quick Context

  • Bootstrap with npm install -g ., verify toolchain versions, then run pnpm build.
  • Use pm context + pm search before creating any new item.
  • Claim before substantial edits and link files/docs/tests as you go.
  • Run sandbox-safe tests before closing items.
  • Never hand-edit tracker records or generated changelog output.

Tracked documentation work: pm-u9d0, pm-oh5h, pm-10ml.

Prerequisites

  • Node.js 20 or newer
  • pnpm 10 or newer
  • Git + GitHub CLI (gh) authenticated for this repository

First-Time Bootstrap (Real Repository Work)

Run from the repository root:

npm install -g .
pm --version
node -v
pnpm -v
pnpm build
export PM_AUTHOR="<stable-agent-id>"

For real repository tracking, do not set PM_PATH.

First Read Path

Use progressive disclosure:

pm context --limit 10
pm search "<request keywords>" --limit 10
pm list-open --limit 20
pm list-in-progress --limit 20
pm install guide-shell --project
pm guide workflows

Then use:

Safe Local Verification

Use sandbox-safe wrappers for test execution:

node scripts/run-tests.mjs test
node scripts/run-tests.mjs coverage

Standard local gate set:

pnpm build
pnpm typecheck
node scripts/run-tests.mjs coverage
pnpm quality:docs-skills
pm validate --check-resolution --check-history-drift

Real Tracker Workflow (Canonical Loop)

  1. Orient and dedupe
pm context --limit 10
pm search "<keywords>" --limit 10
pm list-open --limit 20
pm list-in-progress --limit 20
  1. Claim and start
pm claim <id>
pm update <id> --status in_progress --message "Start implementation"
  1. Link execution context while editing
pm files <id> --add path=src/...,scope=project,note="implementation scope"
pm docs <id> --add path=docs/...,scope=project,note="user-facing behavior"
pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/...",scope=project,timeout_seconds=240
  1. Record progress
pm comments <id> "Progress update and rationale."
pm notes <id> --add "Design tradeoff."
pm learnings <id> --add "Durable lesson."
  1. Verify, close, and release
pm test <id> --run --progress
pm comments <id> "Evidence: linked tests and gates passed."
pm close <id> "Acceptance criteria met; verification passed." --validate-close warn
pm release <id>

Release Overview

  • Daily release prep runs via .github/workflows/auto-release.yml.
  • Tag-triggered publish runs via .github/workflows/release.yml.
  • CHANGELOG.md is generated by pm-changelog and must stay package-generated.

Local parity:

pnpm release:pipeline:dry-run
pnpm release:pipeline

Hard Never-Do List

  • Do not hand-edit CHANGELOG.md (use pnpm changelog:pm only).
  • Do not run manual npm publish for this project.
  • Do not set PM_PATH for real repository mutations.
  • Do not edit .agents/pm/** files directly; mutate through pm commands.
  • Do not bypass governance with destructive git commands unless explicitly approved.

Diagnostics and Recovery

pm health --check-only
pm validate --check-resolution --check-history-drift
pm normalize --dry-run --json
pm package doctor --project --detail summary
pm contracts --command <command> --flags-only --json

If history drift is reported:

pm history-repair <id> --dry-run
pm history-repair <id>

If sensitive content is found in history:

pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run
pm history-redact <id> --literal "<secret>" --replacement "[redacted]"

Private Operations Boundary

Keep credentials, host-specific runbooks, internal topology, and raw private reliability logs out of tracked docs and package output. Keep those details in local, ignored operations notes.

Onboarding remote
Report an issue