pm-presets

All 7 official pm-cli workspace presets in one package.

Install once, get all preset setup commands:

pm install github.com/unbraind/pm-presets --project

Available Presets

Preset	Command	Governance	Best For
bug-triage	pm triage-setup	custom strict-close	Incident response, triage teams
indie-dev	pm indie-setup	minimal	Solo developers, personal projects
open-source	pm oss-setup	standard	OSS maintainers with community contributors
software-sprint	pm sprint-setup	standard	Engineering teams running sprints
startup-roadmap	pm roadmap-setup	custom	Startups with investor-facing roadmaps
kanban	pm kanban-setup	minimal	Continuous-flow boards with a custom Card item type
agent-workflow	pm agent-setup	default	AI agent project management with a custom AgentRun item type

Run pm presets list for the full, machine-readable catalog.

Usage

1. Initialize a pm workspace in your project:

   pm init
   

2. Apply a preset:

   pm triage-setup        # strict bug triage
   pm indie-setup         # minimal solo dev
   pm oss-setup           # open-source project
   pm sprint-setup        # software sprint
   pm roadmap-setup       # startup roadmap
   pm kanban-setup        # continuous-flow kanban
   pm agent-setup        # AI agent project management
   

All setup commands share the same flags:

Flag	Short	Description
--force	-f	Overwrite existing preset template files
--dry-run	-n	Preview changes without writing any files
--prefix	-p	Override the id_prefix in settings.json

Each setup command installs valid pm create templates and registers the templates show runtime handler required by the current pm CLI, so pm create --template <name> works after installing and applying this package.

Managing presets

Beyond the per-preset *-setup aliases, pm-presets ships a unified, read-only management surface plus a generic apply:

Command	Description
pm presets list	Enumerate every bundled preset and what it configures (governance, built-in + custom item types, templates).
pm presets show <id>	Print the full definition of one preset: the settings patch it merges, every template (with its pm create option keys), and any custom item types it registers.
pm presets diff <id>	Compare the current workspace (settings.json + installed templates) against a preset and report what apply would add / change, plus which templates are missing. Add --strict to exit non-zero on drift (CI/compliance).
pm presets validate	Validate that all bundled presets parse and load coherently (governance enums, template names/options, registry↔export agreement).
pm presets apply <id>	Scaffold a preset into the current workspace (the generic form of the *-setup commands). Add --replace for a clean reset of the owned settings trees.
pm presets export <name>	Snapshot the current workspace's settings + templates as a reusable preset definition (JSON), to stdout or a file.

All of the read-only commands accept --json for machine-readable output, and all commands accept --help. An unknown preset id exits with code 3 (NOT_FOUND).

pm presets list
pm presets show software-sprint --json
pm presets diff software-sprint           # what would change if I applied it?
pm presets diff software-sprint --strict  # exit 4 if the workspace has drifted
pm presets validate
pm presets apply software-sprint --dry-run
pm presets apply software-sprint --replace  # clean reset of governance/validation/testing
pm presets export our-config --output our-config.preset.json

Unified presets flags

The bare pm presets command offers a single entry point for the read-only surfaces via flags (the dedicated subcommands above remain available with identical behavior):

Flag	Description
--list	List all bundled workspace presets (same output as pm presets list).
--diff <id>	Compare the current workspace against the named preset (same as pm presets diff <id>); accepts --strict and --json.
--custom <name>	Export the current workspace config as a new preset definition (same as pm presets export <name>); accepts --output, --display-name, and --json.

pm presets --list
pm presets --diff software-sprint --strict
pm presets --custom our-config --output our-config.preset.json

Specify exactly one of --list, --diff, or --custom per invocation.

presets apply flags

presets apply accepts the shared --force / --dry-run / --prefix flags, plus:

Flag	Short	Description
--with-seeds	-s	Also create the preset's starter items after applying it.
--replace		Full-replace the governance / validation / testing trees with the preset's instead of deep-merging them.

Idempotency & safety. apply is safe to re-run:

• settings.json is deep-merged by default — the preset's keys are layered over your existing settings, so unrelated config (telemetry, locks, etc.) is preserved.
• --replace instead swaps the governance / validation / testing trees wholesale with the preset's exact trees — dropping any keys the preset no longer sets, for a clean reset. Unrelated top-level settings (id_prefix, telemetry, locks, …) are still preserved in both modes.
• Templates are skipped if a file with that name already exists; pass --force to overwrite them.
• --dry-run previews every settings merge/replace, template write, and seed item without touching disk.

Drift detection: presets diff --strict

presets diff <id> --strict reuses the diff logic but exits non-zero (code 4) when the workspace is not in sync with the named preset — settings to add/change or templates missing. It prints what drifted (human summary, or the full diff with --json) before exiting, so CI logs explain the failure. When the workspace already matches the preset it exits 0. Plain presets diff (without --strict) always exits 0 and just reports.

# Fail a compliance/CI job if the workspace drifts from the locked preset:
pm presets diff bug-triage --strict || echo "workspace drifted!"

Exporting your own config: presets export

After you apply a preset and customize it, presets export <name> captures the live workspace as a reusable preset definition (settings.json plus every installed template). Write it to stdout (use --json for clean, pipeable output) or to a file with --output:

pm presets apply bug-triage          # start from a bundled preset
# ...customize settings.json and templates by hand...
pm presets export our-config --output our-config.preset.json --display-name "Our Team Config"

The exported document is $schema: "pm-presets/exported-preset@1" and records settings + templates. Custom item-field values are not captured: custom scalar fields have no pm create --<field> setter today (pm-cli #97), so the snapshot reconstructs the preset from settings + templates only.

Seeds and custom fields. Starter items created by --with-seeds set only built-in fields (type, title, priority, tags, body). Custom scalar fields registered via registerItemFields still have no direct pm create --<field> setter, so seed-only context lives in the item body. Registered item-type options are supported through --type-option: the agent-workflow templates persist phase, mode, and model this way while leaving the core pm status field untouched. The kanban Card and agent-workflow AgentRun seeds are created with their registered item types.

Presets in Detail

bug-triage

Governance: custom strict-close — progressive creation with strict ownership and close validation.

Templates: incident, hotfix-task, regression

Default id_prefix: bug-

Best for on-call teams and incident response workflows that need full audit trails.

pm triage-setup
pm create --template incident
pm create --template hotfix-task
pm create --template regression

indie-dev

Governance: minimal — no required fields, no ownership enforcement.

Templates: idea, task

Default id_prefix: indie-

Best for solo developers who want lightweight task tracking with zero ceremony.

pm indie-setup
pm create --template idea
pm create --template task

open-source

Governance: standard — structured without blocking community contributors.

Templates: bug-report, feature-request, good-first-issue

Default id_prefix: oss-

Best for open-source maintainers handling community submissions and milestone releases.

pm oss-setup
pm create --template bug-report
pm create --template feature-request
pm create --template good-first-issue

software-sprint

Governance: standard — sprint format validated, ownership warned.

Templates: epic, feature, task, bug

Default id_prefix: sprint-

Best for engineering teams running two-week sprints with epics and features.

pm sprint-setup
pm create --template epic
pm create --template feature
pm create --template task
pm create --template bug

startup-roadmap

Governance: custom with rich metadata — captures business value and strategic context.

Templates: initiative, feature, milestone

Default id_prefix: road-

Best for startups building investor-facing roadmaps with quarterly planning.

pm roadmap-setup
pm create --template initiative
pm create --template feature
pm create --template milestone

kanban

Governance: minimal — continuous flow with light ownership warnings.

Templates: card, expedite, blocked

Default id_prefix: kan-

Best for teams that pull work through backlog, ready, in-progress, review, and done columns.

pm kanban-setup
pm create --template card
pm create --template expedite
pm create --template blocked

Migration from legacy individual preset packages

If you previously installed individual preset packages, uninstall those legacy entries shown by pm package list --project and install pm-presets instead:

pm package list --project
pm package uninstall <legacy-preset-package> --project
pm install github.com/unbraind/pm-presets --project

The preset commands are identical — only the package name changed.

Programmatic API

import { PRESET_REGISTRY } from "pm-presets/registry";

for (const preset of PRESET_REGISTRY) {
  console.log(preset.id, preset.command, preset.governance);
}

License

MIT

Multi-agent merge safety

This repo tracks its project management in .agents/pm/ and ships a committed .gitattributes that maps those tracker artifacts to pm-cli's field-aware Git merge drivers, so concurrent-branch tracker edits merge cleanly instead of hard-conflicting. Generated extension assets are excluded from semantic merging, while their managed manifest retains key-level JSON merging. The driver definitions live in per-clone Git config; npm install / npm ci wires them automatically via the prepare script, scripts/prepare-merge-driver.ts: the launcher template pm-ops ships, copied unchanged, which a test compares byte for byte with the pinned template. It runs pm-ops's installer, which calls pm merge install when the pm CLI is on PATH and skips with a notice when it is not. A production install of a clone (npm ci --omit=dev) has no pm-ops, so the launcher skips with one notice, while a stale or broken pm-ops fails the install. Registry installs of this package never run prepare. Being Node-based, it behaves identically on POSIX shells and Windows cmd.exe. To (re)run manually: npm run merge:install.

After merging a branch that touched .agents/pm/, reconcile any residual history-hash drift with pm merge reconcile (pm-cli ≥ 2026.7.22): preview with pm merge reconcile --dry-run, apply with pm merge reconcile --message "post-merge reconcile", then confirm with pm validate, which scans the whole tracker and flags remaining history drift across every affected item (pm merge reconcile itself lists each affected stream in its output; pm history --verify <id> spot-checks one item). The field-aware driver already unions every author's content, so reconcile only re-greens the hash chain (no data loss) — see the authoritative pm-cli merge-safety guide. The older blunt pm history-repair --all remains available as a lower-level primitive.