--- name: pm-setup description: Use only when the user explicitly asks to set up, add, or upgrade the pm-* project-management skills in a repository, including merging their rules into an existing AGENTS.md or CLAUDE.md. --- # pm-setup Wire the `pm-*` skills into a repository. Merge their rules into the existing agent instructions file, and check that every `pm-*` skill is installed. Existing content is never rewritten, reordered, or removed. - Source repository: `https://github.com/purview-dev/pm-skills` - Rules to merge: `references/AGENTS-section.md` in this skill's folder. - Skills are installed by the `skills` CLI, not by this skill: `npx skills add -y` (or `bunx skills add -y`) ## Guard - If a workflow skill is active in this conversation (brainstorming, planning, executing, debugging, TDD), do not start. Reply: `Active: at . I'll run pm-setup when this finishes.` - This skill is the fix for the upgrade check (rules: Upgrading before work resumes), so it never runs that check. - The only PM state this skill writes is the `Rules version` line and the missing `Commits` settings in `/config.md`. It never creates or edits any other PM file, and never changes a setting that is already written. - The current folder must be inside a git repository. Work in the **main worktree**: the first path in `git worktree list`. - If `AGENTS.md` or `CLAUDE.md` has uncommitted changes, stop. Reply: `Commit or stash changes to first, so this merge can be reverted with git.` This is the rollback guarantee. ## Step 1: Choose the PM state directory If an existing PM state-directory setting is present in a pm-skills section, preserve it and do not ask again. Otherwise ask this before any other question, as a choice question: `Which folder should hold the planning files?` with the options `planning/ (recommended)` and `Type another folder`. - Use `planning/` if the user accepts the default. - Accept only a repository-relative directory. Reject absolute paths, paths that escape the repository (such as `../private`), and anything inside `.git/`. - Record the selected path in the managed rules as `- PM state directory: planning/`, replacing `planning/` with the user's selection. This setting is the source of truth used by all `pm-*` skills. ## Step 2: Inventory (read-only) Collect these facts. Write nothing yet. 1. **Agent files:** whether `AGENTS.md`, `CLAUDE.md`, and `.claude/CLAUDE.md` exist at the repository root. For each one, record its line endings (LF or CRLF), whether it starts with a UTF-8 BOM, and whether it ends with a newline. 2. **Imports:** whether `CLAUDE.md` contains a line `@AGENTS.md`. 3. **Existing merge and versions:** whether any agent file contains ``, with no version. The version of record is written to `config.md` in item 3. - Upgrade: replace everything from ``, inclusive. Change nothing else. - Repair: when the section heading exists without a start marker, wrap the existing section instead of appending. Insert the start marker before the heading `## Project management layer` and the end marker after the last line of its `## Communication contract` section, which runs to the next level-two heading (`##`) that is not one of the section's own headings, or to the end of the file. Then replace the text between the markers with the reference. Never leave two copies of the section. - Install or reinstall: append to the end of the target file. If the file does not end with a newline, add one, then a blank line, then the section. - Match the target file's existing line endings and BOM. Do not re-wrap, re-indent, or reformat any existing line. 2. **Import.** If Step 3 calls for it, append `@AGENTS.md` on its own line at the end of `CLAUDE.md`, preceded by one blank line. 3. **Version of record.** If `/config.md` exists, set `Rules version` to the skills version from the reference, and create the `## Install` section when it is missing. This is the migration: a legacy `version=` in the old marker becomes this line, and the marker is rewritten without it. Change nothing else in the file. If the file does not exist, say `PM state not initialised: pm-init records Rules version.` 4. **PM config check.** If `/config.md` exists, check that each skill in its Handoffs table exists, and report any that is missing. Then check the `Commits` section (added in version 5) for `PM state commit`, `PM branch`, and `Export on commit` (version 14). For each missing setting, ask one choice question and write the answer under `## Commits`, creating the section before `## Last review` when it is missing: - `PM state commit`: `When a skill writes planning files, how should they be committed?` with `Commit automatically (recommended)`, `Ask me each time`, and `Never commit`, written as `always`, `ask`, or `never`. - `PM branch`: `Which branch should PM state land on?` with the repository's default branch (found as in `pm-init` step 2) marked `(recommended)`, and the current branch when it differs. - `Export on commit`: `Should a PM commit refresh planning.json?` with `Refresh it when it exists (recommended)`, `Always write it`, and `Never refresh it`, written as `if present`, `always`, or `never`. These questions do not count against the one question in Step 4. Do not edit anything else in the file. ## Step 6: Verify 1. Run `git diff --stat` and `git diff` on the agent files. The only changes must be inside the markers, plus the `@AGENTS.md` line if one was added. If anything else changed, revert that file with `git restore -- ` and report the failure. 2. Check that the start marker and end marker each appear exactly once, across all agent files, and that the start marker carries no `version=`. Check that `config.md`, if changed, differs only in its `Rules version` line and the `Commits` settings added in Step 5, item 4. 3. If the repository has a markdownlint config, run `npx markdownlint-cli2 ` (or `bunx markdownlint-cli2 `) on the changed files and report the result. ## Output ```markdown ## pm-setup done - Target: ( | repaired>) - Skills: <24 of 24 installed | missing: names> - Workflow skills: - Rules version: recorded in /config.md | legacy v migrated | PM state not initialised> - Diff check: only the managed section changed, plus the Rules version line and any added Commits settings - Commits: , Export on commit | PM state not initialised> - PM state: - Upgrade gate: | unchanged> ## Do this next 1. Install the missing skills. - Start with: `npx skills add https://github.com/purview-dev/pm-skills -y` - Done when: all 24 pm-* skills are listed by `npx skills list` 2. Install the workflow skills. - Start with: `npx skills add https://github.com/obra/superpowers -y`, or `/plugin install superpowers@claude-plugins-official` in Claude Code (for the default Handoffs table; otherwise the framework the table names) - Done when: every skill in the Handoffs table, and the three named in Non-interruption rule 1, is listed by `npx skills list` 3. Commit. - Start with: `git add && git commit -m "chore: add pm-* skills"`. List only paths that exist, taken from: `.agents/skills/pm-*`, `.claude/skills/pm-*`, `.github/skills/pm-*`, `AGENTS.md`, `CLAUDE.md`, and `/config.md`. - Done when: `git status` is clean 4. ``` Do not run the install or the commit. Print them for the user. ## Upgrading later 1. `npx skills update` updates the skill files. 2. Run `pm-setup` again. It replaces only the section between the markers when the version has changed.