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 22.18 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

For real repository tracking, do not set PM_PATH. Supported agent harnesses are attributed automatically; use --author <stable-agent-id> only when an explicit override is required.

First Read Path

Use progressive disclosure:

pm context --limit 10
pm search "<request keywords>" --limit 10
pm list --status open --limit 20
pm list --status in_progress --limit 20
pm package 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)

The canonical loop is maintained in AGENT_GUIDE.md — this is the condensed contributor version.

Orient and dedupe

pm context --limit 10
pm search "<keywords>" --limit 10
pm list --status open --limit 20
pm list --status in_progress --limit 20

Claim and start

pm claim <id>
pm update <id> --status in_progress --message "Start implementation"

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

Record progress

pm comments <id> "Progress update and rationale."
pm notes <id> --add "Design tradeoff."
pm learnings <id> --add "Durable lesson."

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   # requires the governance-audit package
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.