diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md index dab3992..cf9f3f2 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/release/SKILL.md @@ -11,10 +11,14 @@ Cut a release of `pm-skills`. The version of record is the `version` field in `package.json`. `.github/workflows/release.yml` creates the `v{version}` tag and a GitHub release when `package.json` changes on `main`. -`.github/workflows/ci.yml` requires a version bump in any pull request that -changes `skills/**`, so a skills change cannot merge while `v{version}` -already exists. A pull request that touches nothing under `skills/` (docs, -CI, scripts, `.agents/skills/`) merges without one. +The major is the rules/skills version: the `version=N` start marker in +`skills/pm-setup/references/AGENTS-section.md`. `scripts/check-version.ts` +(CI and pre-push) requires any pull request that changes `skills/**` to +raise that marker past the one on `main`, so a skills change is always a +`major` bump. A pull request that touches nothing under `skills/` (docs, CI, +scripts, package metadata, `.agents/skills/`) keeps the major and may bump +the minor or patch. `scripts/validate.ts` requires this repository's own +`planning/config.md` and `AGENTS.md` to carry the marker version. This skill is repository-only. It lives in `.agents/skills/`, outside the shipped `skills/` set, and its frontmatter sets `metadata.internal: true`, so @@ -27,17 +31,16 @@ inventory, or the `pm-help` guide. - Work in the repository root. Read the version with `node -p 'require("./package.json").version'`. -- If the working tree has uncommitted changes outside `package.json`, stop: - `Commit or stash first.` A release commit changes only - `package.json`. -- Change nothing else: not the skills, the managed section, the README, or the - `Rules version` in `skills/pm-init/templates/config.md`. The release version - and the rules/skills version are independent. -- If the branch changes `skills/pm-setup/references/AGENTS-section.md`, its - `version=N` start marker (and `Rules version` in - `skills/pm-init/templates/config.md`) must already be bumped, or CI fails - the pull request and `pm-setup` would never install the change. The rules - version is separate from the release version. +- If the working tree has uncommitted changes, stop: + `Commit or stash first.` A release commit changes only the files + the bump writes, and, for `major`, the files `pm-setup` writes. +- Change nothing else: not the skills, the README, or the rules text. A + `minor` or `patch` bump writes only `package.json`. A `major` bump also + writes the `version=N` marker and `Rules version` in + `skills/pm-init/templates/config.md`; then `pm-setup` installs the section + in `AGENTS.md` and writes `Rules version` in `planning/config.md`. +- When the branch already raises the marker past `main`, do not bump `major` + again: `package.json` is already `.0.0`. - Never create or delete tags, and never push or merge: print the command instead. The Release workflow owns the tag. - `v{version}` already existing is normal: it is the last release. The point of @@ -50,20 +53,23 @@ inventory, or the `pm-help` guide. (`git log --oneline v{version}..HEAD`). If `v{version}` is not a tag yet, say so: the current version is unreleased, so this skill is only needed if the user wants a different number. -2. **Recommend a part.** From the conventional commits since `v{version}`: - `major` for a breaking change (a `!` after the type or scope, or a - `BREAKING CHANGE:` footer); otherwise `minor` when any `feat` is present; - otherwise `patch`. State the part, the resulting version, and the commits - that decided it. +2. **Recommend a part.** `major` when `git diff --name-only + origin/main...HEAD` lists any path under `skills/` and the marker equals + the one on `main`. Otherwise, from the conventional commits since + `v{version}`: `minor` when any `feat` is present, else `patch`. Never + offer `major` without a skills change. State the part, the resulting + version, and the paths or commits that decided it. 3. **Confirm.** Ask one choice question: `Bump to which version?` with the - recommended `v ()` first, then the other two parts, each - labelled with its version, and `Keep v`. Do not offer a version - that is already tagged. + recommended `v ()` first, then the parts `check-version.ts` + allows, each labelled with its version, and `Keep v`. Do not + offer a version that is already tagged. 4. **Bump.** Run `bun scripts/bump-version.ts ` (or `just bump `). - The script rewrites only the `version` field and fails when the target - `v` tag already exists. -5. **Commit.** `git add package.json`, then - `git commit -m "chore(release): v"`. Do not amend an existing commit. + The script fails when the target `v` tag already exists. After + `major`, run `pm-setup` so `AGENTS.md` and `planning/config.md` carry the + new rules version, then `just validate` and `just version-check`. +5. **Commit.** `git add` the files the bump wrote, then + `git commit -m "chore(release): v"`. `pm-setup` commits + `planning/` itself. Do not amend an existing commit. 6. **Report.** Print the new version, the commit, and the next command: `git push` (or open a pull request). Merging to `main` triggers the Release workflow, which creates the tag and the GitHub release. diff --git a/.config/lefthook.yml b/.config/lefthook.yml index beb4fe3..1eed0c8 100644 --- a/.config/lefthook.yml +++ b/.config/lefthook.yml @@ -7,3 +7,5 @@ pre-push: jobs: - name: lint run: just lint-check + - name: version + run: just version-check diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ebfe86e..48ba839 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -68,10 +68,12 @@ jobs: - name: Build run: bun run build - # A skills change ships in a release, so it needs a new package.json - # version; anything else (docs, CI, scripts, .agents/skills) merges without - # one. A change to the managed rules must also bump the rules version, or - # pm-setup and the upgrade check never see it. + # Mirrors `just version-check` (the lefthook pre-push hook): a skills change + # ships in a release, so it must raise the rules version and package.json + # past the version on main; anything else (docs, CI, scripts, package + # metadata) merges on the same rules version. The validate job keeps + # package.json's major, planning/config.md, and AGENTS.md on the rules + # version, so this repository runs the release it ships. # Scoped to pull requests: on main the release tag already exists. version: name: Version bump @@ -83,53 +85,10 @@ jobs: with: fetch-depth: 0 - - name: Require a version bump for skills changes - shell: bash - env: - BASE: ${{ github.event.pull_request.base.sha }} - run: | - set -euo pipefail - changed="$(git diff --name-only "${BASE}...HEAD")" - - # Non-skills changes (docs, CI, scripts, this file) need no bump. - if ! grep -q '^skills/' <<< "$changed"; then - echo "No skills changed; a version bump is not required." - exit 0 - fi - - read_version() { sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "$1"; } - git show "${BASE}:package.json" > /tmp/base-package.json - current="$(read_version package.json)" - base="$(read_version /tmp/base-package.json)" - if [ -z "$current" ] || [ -z "$base" ]; then - echo "::error::cannot read the version from package.json." - exit 1 - fi - - if [ "$current" = "$base" ]; then - echo "::error::skills changed but package.json is still v${current}. Bump it: run the release skill, or 'just bump patch|minor|major'." - exit 1 - fi - if git rev-parse -q --verify "refs/tags/v${current}" >/dev/null; then - echo "::error::package.json is v${current}, but tag v${current} already exists. Bump it to an unused version." - exit 1 - fi - echo "Skills changed; v${base} -> v${current} is unused." - - # The managed rules only reach a consumer when the rules version - # changes, so a section edit must move version=N (templates/config.md - # follows; scripts/validate.ts keeps the two equal). - section="skills/pm-setup/references/AGENTS-section.md" - if grep -qx "$section" <<< "$changed"; then - marker="$(sed -n 's/^$/\1/p' "$section")" - base_marker="$(git show "${BASE}:${section}" 2>/dev/null | sed -n 's/^$/\1/p' || true)" - if [ -z "$marker" ] || [ -z "$base_marker" ]; then - echo "::error::${section} has no 'version=N' start marker." - exit 1 - fi - if [ "$marker" = "$base_marker" ]; then - echo "::error::${section} changed but its rules version is still v${marker}. Bump version=N in the marker (templates/config.md follows) so pm-setup and the upgrade check take effect." - exit 1 - fi - echo "Rules version bumped v${base_marker} -> v${marker}." - fi + - name: Set up Bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: latest + + - name: Check the version against main + run: bun scripts/check-version.ts "${{ github.event.pull_request.base.sha }}" diff --git a/AGENTS.md b/AGENTS.md index aeb6629..4aec81f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,9 @@ progress, suspends and resumes an operation, commits the PM state, or closes the item on its branch, and `pm-review` triages the roadmap and inbox. `pm-rejoin` re-establishes the position when a session drifts out of the lifecycle. `pm-park` captures ideas (from -the user or the agent) without interrupting active work. `pm-shape` +the user or the agent) without interrupting active work. `pm-pause` writes +the session's position to `PAUSE.md`, with or without an active item, and +`pm-resume` continues from it and deletes it. `pm-shape` discusses and challenges one idea into a brief, `pm-discover` analyses the existing product for evidence, and `pm-strategy` owns vision, milestones, and roadmap generation. `pm-bug` logs a defect with the facts a fix needs @@ -130,36 +132,43 @@ same `bun` commands as the `just` recipes). Markdown is linted with `.agents/skills//SKILL.md` and sets `metadata.internal: true`, which hides it from the `skills` CLI. `just validate` checks its frontmatter and requires the flag; it is exempt from the four consumer tables. -- Bump the release version: `just bump patch|minor|major` - (`scripts/bump-version.ts`). +- Bump the version: `just bump patch|minor|major` + (`scripts/bump-version.ts`; `major` is a rules bump). +- Check the version against main: `just version-check` + (`scripts/check-version.ts`). Hooks are configured in `.config/lefthook.yml`: `commit-msg` runs `bunx commitlint --edit {1}` (rules in `commitlint.config.mts`), and -`pre-push` runs `just lint-check`. +`pre-push` runs `just lint-check` and `just version-check`. -Releases are driven by the `version` field in `package.json`: +Releases are driven by the `version` field in `package.json`, and its major +is the rules/skills version: rules `version=17` ships as `17.x.y`. - `.github/workflows/release.yml` creates the `v{version}` tag and a GitHub release when `package.json` changes on `main`, and skips when the tag already exists. -- `.github/workflows/ci.yml` requires a `package.json` version bump in any - pull request that changes `skills/**`, and refuses a version whose - `v{version}` tag already exists. A pull request that touches nothing under - `skills/` (docs, CI, scripts, this file) merges without a bump. -- A change to the managed section must also bump its `version=N` marker. CI - fails a section change whose marker did not move, because `pm-setup` only - replaces the section when the version changes; otherwise the fix never - reaches a consumer. `scripts/validate.ts` keeps - `skills/pm-init/templates/config.md` equal to the marker, and `pm-setup` - writes it to the consumer's `Rules version`. -- `just bump patch|minor|major` (`scripts/bump-version.ts`) writes the next - version and refuses one that is already tagged. The repository-only - `release` skill (`.agents/skills/release/SKILL.md`) picks the part from - the conventional commits since the last tag, bumps, and commits. -- The release version and the rules/skills version are independent: the - rules/skills version is the `version=N` marker in the managed section - (mirrored by `Rules version` in a consumer's `config.md`), bumped by hand - when that section changes. +- `scripts/validate.ts` keeps the versions equal, so the repository runs the + release it ships: the `package.json` major, + `skills/pm-init/templates/config.md`, `Rules version` in + `planning/config.md`, and the section installed in this file all match the + `version=N` marker. `pm-setup` writes the last two. +- `scripts/check-version.ts` compares the branch with the version on `main` + (CI: the pull request base; pre-push: the merge base with `origin/main`). + A pull request that changes `skills/**` must raise the marker past the one + on `main`, so a released version is never merged again, and must use a + `package.json` version with no `v{version}` tag. A pull request that + touches nothing under `skills/` (docs, CI, scripts, package metadata, this + file) keeps the rules version; it may keep `package.json` or raise its + minor or patch. +- `just bump major` raises the marker, the config template, and + `package.json` to `.0.0`; then run `pm-setup` to install the rules + here. `just bump minor|patch` raises `package.json` only, for a release + without a skills change. The script refuses a version that is already + tagged. The repository-only `release` skill + (`.agents/skills/release/SKILL.md`) picks the part, bumps, and commits. +- Every skills change is a rules bump, so a consumer's `pm-resume` asks it + to run `pm-setup` and the change reaches it. Add a `Version N` line to the + upgrade notes in the managed section when the rules themselves change. ## Repository conventions @@ -210,7 +219,7 @@ repository root. | --- | --- | --- | | `pm-setup` | Install or upgrade these skills and this section | User asks | | `pm-init` | Create the PM root, write `VISION.md`, seed the roadmap | User asks | -| `pm-resume` | Show where work stopped and the next action for the agent and the user | Session start, after compaction, or user asks | +| `pm-resume` | Show where work stopped and the next action for the agent and the user; continue a pause and delete its file | Session start, after compaction, or user asks | | `pm-rejoin` | Find the true position in the lifecycle from git and PM state, then rejoin at the right stage | Drifted or detached from the lifecycle, NOW.md disagrees with the work, user asks "where am I" | | `pm-next` | Pick and claim the next claimable item on its own feature branch, hand off to design | No active item, user asks | | `pm-park` | Capture an idea, bug, question, or inspiration without derailing | Any time (capture mode only during a workflow) | @@ -221,6 +230,7 @@ repository root. | `pm-strategy` | Set vision, milestones, bets, and decisions; generate or re-plan the roadmap | User asks, or another PM skill recommends it | | `pm-purview` | Recommend Purview (purview.dev) .NET tools only where they add value; ask about stack and scale for new projects | User asks, or `pm-init`, `pm-discover`, `pm-shape`, `pm-strategy` find a .NET need it covers | | `pm-checkpoint` | Save state at a stopping point; suspend and resume an operation on the stack; close finished items on their branch | Session end, before compaction, stage end, user asks | +| `pm-pause` | Write the session's position (the step in progress, the open question, the next action) to the pause file, which `pm-resume` continues from and deletes | User asks to pause, including mid-workflow | | `pm-revise` | Correct work that is not what the user wanted: rewind the active item, fix it in place, or open a revision item | User asks, or a `Done when` check fails, including mid-workflow | | `pm-review` | Weekly triage of inbox and roadmap | User asks, or `pm-resume` says review is due | | `pm-item` | Add, edit, drop, block, unblock, move (including position), reassign, or complete one roadmap item | User asks | @@ -278,11 +288,17 @@ Every `pm-*` skill uses these definitions. The skills do not redefine them. merged. It is reversible: `pm-revise` (`fix-in-place`) removes the `## Done` line and restores `NOW.md` at `execute`, and the fix re-runs the finish order on the same pull request. -- **Reference legend:** the short list of the IDs a question uses, each with - the words needed to decide it: a milestone's name, whether it is the - focus, and the items in it; a roadmap item's title, owner, size, and - status; a risk's title, RAG, and status; a `V` line, bet, or inbox file's - one-line text. A question that names IDs prints it (Asking the user). +- **Reference legend:** the short list of the IDs a question or a + discussion uses, each with the words needed to decide it: a milestone's + name, whether it is the focus, and the items in it; a roadmap item's + title, owner, size, status, and section position (`Next 3`, `Later, M2`); + a risk's title, RAG, and status; a `V` line, bet, or inbox file's + one-line text. It lists every member of a range, not its ends: `M1 to + M4` lists M1, M2, M3, and M4, and `R-005 to R-010` lists every item + between them in roadmap order. A position (`before R-010`, `after M2`) + lists the item or milestone it names and its neighbours on each side, so + the user sees where the new position falls. It is printed first, before + the text that uses the IDs (Asking the user, Communication contract). - **Named reference:** an ID written with the words that identify it, so the user never has to look a bare ID up. In a list, board, roadmap, or status it is ` `; in a question, choice, or change line it is @@ -348,6 +364,16 @@ Every `pm-*` skill uses these definitions. The skills do not redefine them. does not export it. A **stack entry** holds the item, its `Done when`, the branch, the stage, the brief, spec, plan, milestone, started date, the reason it was suspended, and its checkpoint block. +- **Pause file:** `<PM root>/PAUSE.md`, the session's position written by + `pm-pause`: `Paused`, `Session` (a branch, matched like `NOW.md`), + `Item`, `Running` (the skill or workflow and its step), `Files`, the + uncommitted files outside the PM root, and a `## Resume with` block + (`Next action`, `Start with`, `Open question`) and `## Context`. It holds + one pause and points to the PM files that hold the decisions; it never + holds a decision only. Optional: a missing file means no pause. + `pm-resume` continues a pause whose `Session` matches and then deletes + the file, the one write `pm-resume` makes. It is session memory, so + `pm-export` does not export it. - **Bug:** an inbox file with `Kind: bug`, written by `pm-bug`, carrying `Severity`, `Affects`, and a `## Reproduction` block. It is triaged like any other inbox file (`pm-review`), shaped when the fix needs design @@ -583,6 +609,7 @@ might apply"). That rule does **not** apply to `pm-*` skills, except - as the item's completion step, after the execute stage passes its `Done when` checks and before the finish step pushes the branch (`pm-checkpoint`, `done` only), or + - when the user asks to pause the session (`pm-pause`), or - when the agent parks its own finding (`pm-park`, capture mode), or - when the user or the agent names a risk (`pm-risk`, capture mode). 3. **Mid-workflow, the only permitted PM writes are `pm-park` and @@ -606,10 +633,11 @@ might apply"). That rule does **not** apply to `pm-*` skills, except or reorder anything during a workflow. In every case the step in progress resumes afterwards. The PM write exceptions are rule 8 (`pm-revise`), rule 10 (`pm-checkpoint` push and pop), the stage update in - rule 2 (`pm-checkpoint` after a design or plan handoff), and the + rule 2 (`pm-checkpoint` after a design or plan handoff), the completion step in rule 2 (`pm-checkpoint` `done`, on the item's branch - before the finish step); rule 9 covers the docs site, which is not PM - state. + before the finish step), and `pm-pause` when the user asks to pause, + which ends the workflow at its step (rule 1) and writes the **Pause + file**; rule 9 covers the docs site, which is not PM state. 4. **If the user names another PM skill mid-workflow**, do not run it. Ask one choice question: `<skill> is at <step>. When should <pm-skill> run?` with the options `After <skill> finishes (recommended)` and `Pause now @@ -780,6 +808,9 @@ PM files are the only memory that survives compaction and new sessions. content contradicts the files, the files are correct. - Before a session ends, or when context is about to be compacted, with an item active, run `pm-checkpoint` (pause). +- When the user asks to pause the session, run `pm-pause`. It also covers + a PM operation or question in progress with no item active, and + `pm-resume` continues from its **Pause file**, then deletes it. ## Context budget (mandatory) @@ -1045,6 +1076,16 @@ search, and hand the write to a non-blocking background task when the agent has one, so the step in progress does not wait. `pm-review` runs the skipped `Related` search when it triages the file. No setting is added. +Version 17 shows referenced IDs first. Output that discusses `V` lines, +milestones, bets, or items prints a `## For this discussion` legend before +the text that names them, and every legend lists each member of a range +(`M1 to M4`) and the neighbours of a position (`after R-010`). Version 17 +also adds `pm-pause` and the **Pause file**: `pm-pause` writes the +session's position to `<PM root>/PAUSE.md`, and `pm-resume` continues from +it and deletes it. A missing file means no pause. From version 17 the +release major is the rules version, so every skills release is a rules +upgrade. No setting is added. + ## Asking the user (mandatory) - **Every question uses the agent's interactive question tool** (for @@ -1064,8 +1105,10 @@ skipped `Related` search when it triages the file. No setting is added. bet, `V` line, brief, or inbox file by ID alone. Print a `## For this question` legend (Communication contract) above the question, listing each ID it names with the words needed to decide it (Shared definitions: Reference - legend). Keep it to the IDs the question uses; do not print the whole - roadmap. + legend). A range lists every member and a position lists its neighbours, + so `Move R-005 after R-010?` and `Re-plan M1 to M4?` are never asked + without them. Keep it to the IDs the question uses; do not print the + whole roadmap. - **Offer a way to see more.** Add one escape option after the decision options; it does not count towards the 2 to 4 and is never an answer. `Explain <ID>` when the question names IDs, `Show the roadmap` for a @@ -1109,6 +1152,13 @@ Output must be literal, predictable, and immediately actionable. the plan, brief, or conversation. - Before a question that names IDs, print the `## For this question` legend (Asking the user). It is the only section a question adds. +- **Show before discussing.** When output discusses, compares, challenges, + or proposes a change to `V` lines, milestones, bets, or items (shaping, + strategy, review, reordering, re-planning) and names them by ID, print a + `## For this discussion` legend first (Shared definitions: Reference + legend), before any sentence that uses the IDs. One legend covers the + discussion; print it again only for IDs it does not list. A question in + the same output reuses it instead of adding `## For this question`. - At most 5 bullets per section, except boards, tables, and lists that a skill's template defines as complete. At most 3 sentences per paragraph. - State any assumption explicitly as `Assumption: ...`. diff --git a/README.md b/README.md index b8e188d..096131e 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,7 @@ Then, in your agent: | [`pm-strategy`](skills/pm-strategy/SKILL.md) | Milestones, focus, bets, decisions; generate or re-plan the roadmap | User asks | | [`pm-purview`](skills/pm-purview/SKILL.md) | Recommend [Purview](https://purview.dev/) .NET tools only where they add value | New project, or a matching .NET need | | [`pm-checkpoint`](skills/pm-checkpoint/SKILL.md) | Save state and decisions, record stage changes, suspend or resume an operation, close finished items on their branch | Session or stage end, before compaction, an emergency pause | +| [`pm-pause`](skills/pm-pause/SKILL.md) | Write the session's position (step in progress, open question, next action) for `pm-resume` to continue and then delete | You stop mid-task, with or without an active item | | [`pm-review`](skills/pm-review/SKILL.md) | Triage the inbox, check roadmap health, order Next | Weekly | | [`pm-item`](skills/pm-item/SKILL.md) | Add, edit, drop, block, move or insert at a position, reassign, or complete one item | User asks | | [`pm-board`](skills/pm-board/SKILL.md) | Task board; move, add, insert, or close one card | User asks | @@ -202,6 +203,7 @@ directory selected during `pm-setup`. | `planning/ROADMAP.md` | Next (ordered, maximum 5) and Later, with owner and dependencies | | `planning/LOG.md` | Done, Dropped, Reviews | | `planning/STACK.md` | Suspended operations, newest first, with their checkpoints | +| `planning/PAUSE.md` | The paused session's position, written by `pm-pause`; deleted once `pm-resume` continues it | | `planning/RISKS.md` | The risk register: open, closed, and removed risks with likelihood, impact, and RAG | | `planning/inbox/` | The parking lot: one file per idea | | `planning/briefs/` | One shaped idea per file: challenges, ramifications, decision | @@ -343,19 +345,22 @@ Requires [`bun`](https://bun.sh) and, for the git hooks, - `just install` verifies the tools and installs the git hooks (commitlint on commit, `just lint-check` on push). - `just bump patch|minor|major` writes the next release version to - `package.json`. + `package.json`; `major` also raises the rules version. +- `just version-check` compares the version with `main` (also run on push). This repository manages itself with these skills: `planning/` is its live PM state, and `docs-site/` is the site `pm-docs-site` builds from it. -CI runs the same checks on every push and pull request to `main`. A pull -request that changes anything under `skills/` must also bump the -`package.json` version to one that is not already tagged, and a change to -the managed rules must bump the rules version too, or `pm-setup` would never -install it. Pull requests that touch nothing under `skills/` (docs, CI, -scripts) merge without a bump. The repository-only `release` skill in -`.agents/skills/release/` picks the bump from the conventional commits since -the last tag and commits it; it is not installed into consuming projects. +The `package.json` major is the rules/skills version (rules v17 ship as +`17.x.y`), and this repository must run what it ships: its own +`planning/config.md` and `AGENTS.md` carry the same rules version. CI runs +the same checks on every push and pull request to `main`. A pull request +that changes anything under `skills/` must raise the rules version past the +one on `main` (`just bump major`, then `pm-setup`), to a version that is not +already tagged. Pull requests that touch nothing under `skills/` (docs, CI, +scripts, package metadata) keep the rules version, and may bump the minor +or patch. The repository-only `release` skill in `.agents/skills/release/` +picks the bump and commits it; it is not installed into consuming projects. Adding a skill means creating `skills/<name>/SKILL.md` and listing it in the README table, the managed-section table, the `pm-setup` inventory, and the diff --git a/justfile b/justfile index 3fd4bf3..86b0f0a 100644 --- a/justfile +++ b/justfile @@ -26,10 +26,14 @@ lint-check: validate lint-fix: bunx markdownlint-cli2 --fix "**/*.md" "#node_modules" -# Bump the release version in package.json (patch, minor, or major). +# Bump package.json (patch, minor, or major; major also bumps the rules version). bump part: bun scripts/bump-version.ts {{part}} +# Check the version against main (default: the merge base with origin/main). Used by the lefthook pre-push hook. +version-check base="": + bun scripts/check-version.ts {{base}} + # Serve the project site (plan, README, every skill) at http://localhost:4321. Requires Bun. [group('Docs')] [working-directory('docs-site')] diff --git a/package.json b/package.json index 15be6e4..42b720e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pm-skills", - "version": "0.13.0", + "version": "17.0.0", "description": "Project-management skills for solo developers using AI coding agents - a parking lot, challenged shaping, strategy, roadmap, task board, up-next queue, and session memory, installed above a development workflow skill set such as Superpowers.", "license": "MIT", "author": { diff --git a/planning/config.md b/planning/config.md index 75a379a..05e42d5 100644 --- a/planning/config.md +++ b/planning/config.md @@ -10,7 +10,7 @@ Read by every `pm-*` skill. Change behaviour here, not in the skills. ## Install -- Rules version: 15 +- Rules version: 17 ## Handoffs diff --git a/scripts/bump-version.ts b/scripts/bump-version.ts index 848a6be..c95fa10 100644 --- a/scripts/bump-version.ts +++ b/scripts/bump-version.ts @@ -4,6 +4,8 @@ import { join } from "node:path"; const root = join(import.meta.dir, ".."); const pkgPath = join(root, "package.json"); +const sectionPath = join(root, "skills", "pm-setup", "references", "AGENTS-section.md"); +const configPath = join(root, "skills", "pm-init", "templates", "config.md"); const parts = ["patch", "minor", "major"] as const; type Part = (typeof parts)[number]; @@ -28,10 +30,24 @@ if (!semver) { process.exit(1); } +// The major is the rules/skills version (the version=N marker), so a major +// bump is a rules bump: it moves the marker and the config template with it. +const section = readFileSync(sectionPath, "utf8"); +const marker = /<!-- pm-skills:start version=(\d+) -->/.exec(section); +if (!marker) { + console.error("AGENTS-section.md: no version=N start marker"); + process.exit(1); +} +const rules = Number(marker[1]); + const [major, minor, patch] = semver.slice(1).map(Number); +if (major !== rules) { + console.error(`package.json major ${major} != rules version ${rules}. Set package.json to ${rules}.0.0 first.`); + process.exit(1); +} const next = part === "major" - ? `${major + 1}.0.0` + ? `${rules + 1}.0.0` : part === "minor" ? `${major}.${minor + 1}.0` : `${major}.${minor}.${patch + 1}`; @@ -49,3 +65,10 @@ if (tagged) { writeFileSync(pkgPath, text.replace(match[0], `${match[1]}${next}${match[3]}`)); console.log(`v${current} -> v${next}`); + +if (part === "major") { + writeFileSync(sectionPath, section.replace(marker[0], `<!-- pm-skills:start version=${rules + 1} -->`)); + const config = readFileSync(configPath, "utf8"); + writeFileSync(configPath, config.replace(/^- Rules version: \d+$/m, `- Rules version: ${rules + 1}`)); + console.log(`rules v${rules} -> v${rules + 1}. Run pm-setup to install them here (AGENTS.md and planning/config.md).`); +} diff --git a/scripts/check-version.ts b/scripts/check-version.ts new file mode 100644 index 0000000..b6efe05 --- /dev/null +++ b/scripts/check-version.ts @@ -0,0 +1,76 @@ +import { execFileSync } from "node:child_process"; +import { join } from "node:path"; + +// Compares HEAD with the version already merged to main, so a released version +// is never merged twice. CI passes the pull request's base commit; the +// pre-push hook defaults to the merge base with origin/main. +// +// - A change under skills/ ships in a release: it must raise the rules version +// (the version=N marker) and package.json, to a version not already tagged. +// scripts/validate.ts keeps package.json's major equal to the marker and +// planning/config.md on it, so the bump is dogfooded here first. +// - Anything else (docs, CI, scripts, package metadata) may keep the version, +// or raise minor or patch within the same rules version. + +const root = join(import.meta.dir, ".."); +const section = "skills/pm-setup/references/AGENTS-section.md"; +const git = (...args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8" }).trim(); +const tryGit = (...args: string[]) => { + try { + return git(...args); + } catch { + return ""; + } +}; + +let base = process.argv[2]; +if (!base) { + if (!tryGit("rev-parse", "-q", "--verify", "origin/main")) { + console.log("check-version: no origin/main; skipped (CI runs it)."); + process.exit(0); + } + base = git("merge-base", "HEAD", "origin/main"); +} + +const marker = (text: string) => /<!-- pm-skills:start version=(\d+) -->/.exec(text)?.[1]; +const version = (text: string) => JSON.parse(text).version as string; +const parse = (v: string) => /^(\d+)\.(\d+)\.(\d+)$/.exec(v)?.slice(1).map(Number); +const compare = (a: number[], b: number[]) => a.findIndex((n, i) => n !== b[i]); + +const errors: string[] = []; +const current = { version: version(git("show", "HEAD:package.json")), marker: marker(git("show", `HEAD:${section}`)) }; +const merged = { version: version(git("show", `${base}:package.json`)), marker: marker(tryGit("show", `${base}:${section}`)) }; +const now = parse(current.version); +const was = parse(merged.version); +if (!now) errors.push(`package.json: version "${current.version}" is not MAJOR.MINOR.PATCH`); +if (!current.marker) errors.push(`${section}: no version=N start marker`); + +const changed = git("diff", "--name-only", `${base}...HEAD`).split("\n").filter(Boolean); +const skills = changed.some((p) => p.startsWith("skills/")); +const bumped = current.version !== merged.version; + +if (now && was) { + const i = compare(now, was); + if (i !== -1 && now[i] < was[i]) errors.push(`package.json: v${current.version} is older than v${merged.version} on main`); +} +if (skills) { + if (current.marker && merged.marker && Number(current.marker) <= Number(merged.marker)) { + errors.push( + `skills changed but rules v${current.marker} is already on main. Run 'just bump major', then pm-setup, so this release is v${Number(merged.marker) + 1}.`, + ); + } + if (!bumped) errors.push(`skills changed but package.json is still v${current.version}, the version on main.`); +} +if (bumped && tryGit("tag", "--list", `v${current.version}`)) { + errors.push(`package.json is v${current.version}, but tag v${current.version} already exists.`); +} + +if (errors.length) { + console.error(errors.map((e) => `- ${e}`).join("\n")); + process.exit(1); +} +console.log( + skills + ? `check-version: skills changed; v${merged.version} -> v${current.version}, rules v${merged.marker} -> v${current.marker}.` + : `check-version: no skills changed; v${current.version}${bumped ? ` (was v${merged.version})` : ""}.`, +); diff --git a/scripts/validate.ts b/scripts/validate.ts index 471c941..9fc915c 100644 --- a/scripts/validate.ts +++ b/scripts/validate.ts @@ -74,6 +74,24 @@ if (sectionVersion && templateVersion !== sectionVersion) { ); } +// The release is the rules/skills version: package.json is <N>.<minor>.<patch> +// with N the marker version, so a release and the rules it ships never differ. +const pkgVersion = JSON.parse(read("package.json")).version as string; +const pkgMajor = /^(\d+)\.\d+\.\d+$/.exec(pkgVersion)?.[1]; +if (!pkgMajor) fail(`package.json: version "${pkgVersion}" is not MAJOR.MINOR.PATCH`); +else if (sectionVersion && pkgMajor !== sectionVersion) { + fail(`package.json: version ${pkgVersion} major != rules version ${sectionVersion} (run just bump major)`); +} + +// This repository dogfoods its own release: its PM state must record the rules +// it ships, which pm-setup writes when it installs them. +if (existsSync(join(root, "planning", "config.md"))) { + const ownVersion = /^- Rules version: (\d+)$/m.exec(read("planning", "config.md"))?.[1]; + if (sectionVersion && ownVersion !== sectionVersion) { + fail(`planning/config.md: Rules version ${ownVersion ?? "missing"} != AGENTS-section version ${sectionVersion} (run pm-setup)`); + } +} + const templates = join(skillsDir, "pm-init", "templates"); const initText = read("skills", "pm-init", "SKILL.md"); for (const m of initText.matchAll(/^\| `([^`]+\.md)` \| `<PM root>\/[^`]+` \|$/gm)) { diff --git a/skills/pm-export/SKILL.md b/skills/pm-export/SKILL.md index 92f83d2..7811153 100644 --- a/skills/pm-export/SKILL.md +++ b/skills/pm-export/SKILL.md @@ -41,7 +41,7 @@ Completion record. `write` applies Non-interruption rule 4. - Export only what the PM files hold. Never add environment values, tokens, source-code excerpts, or anything not in the PM root. Never export - `STACK.md`: it is session memory, not plan. + `STACK.md` or `PAUSE.md`: they are session memory, not plan. - Never edit any other PM file. This skill reads them all and writes two. - Anyone can validate the result with `bunx ajv-cli@5 validate -s "<PM root>/planning.schema.json" -d "<PM root>/planning.json" --spec=draft2020`. @@ -158,7 +158,7 @@ Remaining objects: 1. Read every PM file: `config.md`, `VISION.md`, `STRATEGY.md`, `NOW.md`, `ROADMAP.md`, `LOG.md`, `RISKS.md`, `inbox/`, and `briefs/` (`STACK.md` - is not exported). A missing optional file is empty (Shared definitions: + and `PAUSE.md` are not exported). A missing optional file is empty (Shared definitions: Optional files). 2. Build the document in the field-map order, applying the format rules. Where a value is not written in the file, use `null`, never a guess; state diff --git a/skills/pm-help/SKILL.md b/skills/pm-help/SKILL.md index c31cf12..eff7b78 100644 --- a/skills/pm-help/SKILL.md +++ b/skills/pm-help/SKILL.md @@ -39,7 +39,7 @@ asked, the skill's own `SKILL.md` steps. | --- | --- | --- | --- | | `pm-setup` | Installing or upgrading the skills and the rules in `AGENTS.md` or `CLAUDE.md` | "set up the pm skills" | The managed section only | | `pm-init` | Starting project management in a repository, once | "initialise planning" | The PM root, `VISION.md`, a seeded roadmap | -| `pm-resume` | Starting a session, or after the context was compacted | "where was I?" | Nothing | +| `pm-resume` | Starting a session, or after the context was compacted | "where was I?" | Nothing, except deleting `PAUSE.md` once its pause resumes | | `pm-rejoin` | You lost the pm thread, a workflow is running that `NOW.md` does not record, or a session started mid-task | "where am I in the pm lifecycle?", "rejoin", "get back on track" | `NOW.md`, `ROADMAP.md` | | `pm-next` | Nothing is active and you want to start the next item on its own feature branch | "start R-007", "claim R-007" | `NOW.md`, `ROADMAP.md` | | `pm-park` | You or the agent have an idea, bug, question, or inspiration to remember, even mid-task | "park this: ...", "note that ..." | One inbox file | @@ -50,6 +50,7 @@ asked, the skill's own `SKILL.md` steps. | `pm-strategy` | Setting focus, milestones, bets, or the vision, or rebuilding the roadmap | "re-plan the roadmap" | `STRATEGY.md`, `VISION.md`, `ROADMAP.md` | | `pm-purview` | A .NET project wants to know which Purview tools would help, or a new project is choosing its stack | "would Purview help here?" | A research report; roadmap items if accepted | | `pm-checkpoint` | Stopping, pausing, switching items, suspending or resuming an operation, or finishing one (a finished item ends its context) | "pause", "stack this, I need to fix the build", "pop the stacked work", "R-007 is done" | `NOW.md`, `LOG.md`, `ROADMAP.md`, `STACK.md` | +| `pm-pause` | Stopping mid-task and continuing later from the exact step, with or without an active item (a shaping interview, a review, a question waiting for you) | "pause here", "save where we are, I'll pick this up tomorrow" | `PAUSE.md`; the active item's checkpoint in `NOW.md` | | `pm-revise` | Work that is already built is not what you wanted, or a `Done when` check fails, including mid-workflow | "that's not right", "change what we built for R-007" | `NOW.md`, `ROADMAP.md`, the brief's `## Revisions` | | `pm-review` | Weekly, or when `pm-resume` says a review is due | "weekly review" | Inbox, `ROADMAP.md`, `LOG.md`, `config.md` | | `pm-item` | Changing one roadmap item: add, edit, drop, block, move or insert at a position, reassign, or mark a task of yours done | "drop R-012", "put R-012 before R-008", "I've done R-009" | `ROADMAP.md`, `LOG.md` | @@ -77,7 +78,8 @@ inside a workflow (rule 9), completion records and the finish order (the completion commit rides the item's branch and its pull request), feature branches (each item on its own branch, staying put when asked, during an interruption, or while a pull request is pending, and pulling before every -move), the operation stack and `pm-checkpoint` push/pop, `merged-unclosed` items, +move), the operation stack and `pm-checkpoint` push/pop, the pause file +(`pm-pause` writes it, `pm-resume` continues and deletes it), `merged-unclosed` items, named references (why an ID always carries its title), the Context budget (one item per context, a fresh session between items), and the two ways a workflow may be interrupted (`pm-revise` to correct, `pm-checkpoint` @@ -114,6 +116,7 @@ push/pop to suspend). | 22 | No open risk in `RISKS.md` has `Reviewed: never`, and every red open risk has a `Mitigation` other than `none` | `<n> unreviewed risks`, or `Red risk without a mitigation: RK-NNN <title>` | `pm-risk review`, or `pm-risk mitigate <RK-NNN>` | | 23 | The `Commits` section of `config.md` sets `PM state commit`, `PM branch`, and `Export on commit` | `Commits setting missing: <names>` (PM commits ask, or the export lags) | `pm-setup` | | 24 | If an item is active, its `Session` is not the PM branch, and `git rev-list --count HEAD..@{upstream}` is 0 (against the remote refs already fetched) | `<ID> <title> is on the PM branch` (expected only when the user asked to stay there), or `<branch> is <n> commits behind <upstream>` | `pm-rejoin`, or `git pull --ff-only` | + | 25 | `PAUSE.md` is missing | `Paused on <Session> at <Paused>: <Running>` | `pm-resume` on `<Session>` | Stop at the first failing check among 1 to 4; later checks depend on them. diff --git a/skills/pm-init/templates/config.md b/skills/pm-init/templates/config.md index d3fb02c..2cc3259 100644 --- a/skills/pm-init/templates/config.md +++ b/skills/pm-init/templates/config.md @@ -10,7 +10,7 @@ Read by every `pm-*` skill. Change behaviour here, not in the skills. ## Install -- Rules version: 16 +- Rules version: 17 ## Handoffs diff --git a/skills/pm-pause/SKILL.md b/skills/pm-pause/SKILL.md new file mode 100644 index 0000000..2f79b05 --- /dev/null +++ b/skills/pm-pause/SKILL.md @@ -0,0 +1,108 @@ +--- +name: pm-pause +description: Use when the user asks to pause the session, save where they are, or stop now and continue later ("pause here", "save state, I'll pick this up tomorrow"), with or without an active item, including mid-workflow. Writes the current position - the skill or workflow step in progress, the open question, the files in use, and the one next action - to the pause file, checkpoints the active item, and commits the PM state. pm-resume continues from the pause file and deletes it. +--- + +# pm-pause + +Write down where the session is, so the next session continues from the +exact step without the conversation. It covers what `NOW.md` does not +hold: a PM operation in progress (`pm-shape` at its third question, +`pm-review` at inbox file 4 of 9), a question waiting for the user, or a +workflow step. `pm-resume` reads the pause file first, continues from it, +and deletes it. + +Follow the Non-interruption rules, Shared definitions, Persistence, Context +budget, Committing PM state, Asking the user, and Communication contract in +the pm-skills section of the agent instructions file (`AGENTS.md` or +`CLAUDE.md`). PM root is its `PM state directory` setting (default +`planning/`). + +## Guard + +- If `<PM root>/config.md` or `<PM root>/NOW.md` is missing, reply: + `No <PM root> state. Run pm-init.` Stop. +- It runs mid-workflow only when the user asks to pause (Non-interruption + rules 1 and 2): the user's pause ends the workflow at the step in + progress. It never starts on its own. +- It never runs the upgrade check (rules: Upgrading before work resumes): + saving the state comes first. +- If `NOW.md` is active and its `Session` does not match the current + session (Shared definitions), the item belongs to another session: write + the pause file without the item, and add the Note `<ID> <title> belongs + to <Session>; its checkpoint is not changed.` +- If the **Pause file** exists with a different `Session`, show its + `Paused`, `Session`, and `Next action`, then ask one choice question: + `A pause for <Session> from <Paused> is waiting. Replace it?` with the + options `Keep it and stop (recommended)` and `Replace it`. On keep, stop + with nothing written. A pause with the same `Session` is replaced + without asking. + +## Steps + +1. **Read the position.** Timestamp (Shared definitions), the current + branch (`git branch --show-current`), `NOW.md`, and + `git status --porcelain` for changed files outside the PM root. From + this session, name the skill or workflow in progress and its step, the + question waiting for the user, and the PM files it uses (brief, spec, + plan, research report, inbox file). +2. **Write through first** (rules: Persistence). Every decision and answer + from this session must already be in its file: the brief, the research + report, `STRATEGY.md`, or an inbox file. Write any that is missing to + that file now, under the heading its skill uses. The pause file points + to them and never holds a decision only. +3. **Checkpoint the item.** When `NOW.md` is active for this session, + apply `pm-checkpoint` (`pause`) steps 1, 2, and 4: park follow-ups and + replace `## Checkpoint`. Its step 9 commit is replaced by step 5 here. +4. **Write the pause file.** Write `<PM root>/PAUSE.md`, replacing any pause + for this session, with real values: + + ```markdown + # Pause + + - Paused: <YYYY-MM-DD HH:MM> + - Session: <branch> + - Item: <ID title (stage) | none> + - Running: <skill or workflow, and its step | none> + - Files: <PM root paths, spec, or plan in use | none> + - Uncommitted outside PM root: <n files: paths | none> + + ## Resume with + + - Next action: <one action> + - Start with: <skill and mode, exact command, or file path> + - Open question: <the question waiting for the user, verbatim | none> + + ## Context + + - <facts the next session needs that no PM file holds, at most 5 | none> + ``` + + With an active item, `Next action` and `Start with` equal its new + checkpoint. `Context` holds only what is not in the brief, spec, plan, + or checkpoint (rules: Context budget), never a transcript. +5. **Commit** the PM state (rules: Committing PM state) with + `docs(pm): pause session on <branch>`. Files outside the PM root are + listed in the pause file and the `Note`; never stage or commit them. + +## Output + +```markdown +## Paused + +- Session: <branch> +- Item: <ID Title (stage) | none> +- Running: <skill or workflow, and its step | none> +- Open question: <text | none> +- Pause file: <PM root>/PAUSE.md + +## Do this next + +1. Resume in the next session. + - Start with: `pm-resume` on `<branch>` + - Done when: `pm-resume` shows this pause and `<PM root>/PAUSE.md` is deleted after it resumes + +## Note + +- <commit result, uncommitted files outside the PM root, an item owned by another session> +``` diff --git a/skills/pm-resume/SKILL.md b/skills/pm-resume/SKILL.md index 2c36f09..7812c28 100644 --- a/skills/pm-resume/SKILL.md +++ b/skills/pm-resume/SKILL.md @@ -1,14 +1,15 @@ --- name: pm-resume -description: Use at the start of a session, after the context has been compacted, or when the user asks where work stopped or what to do next. Reads the PM state and reports the next action for the agent, the user's own queue, and anything waiting for discussion. Read-only. +description: Use at the start of a session, after the context has been compacted, or when the user asks where work stopped or what to do next. Reads the PM state and any pause left by pm-pause, and reports the next action for the agent, the user's own queue, and anything waiting for discussion. Read-only, except that it deletes the pause file once that pause resumes. --- # pm-resume Report where work stopped, the one next action, and what is waiting for -the user. Read-only. After compaction, this is how the session gets its -memory back: the PM files win over anything recalled from the -conversation. +the user. Read-only, except for the **Pause file**: when this session +resumes a pause, `pm-resume` deletes the file and commits the deletion. +After compaction, this is how the session gets its memory back: the PM +files win over anything recalled from the conversation. Follow the Non-interruption rules, Shared definitions, Persistence, Asking the user, and Communication contract in the pm-skills section of the agent @@ -36,8 +37,8 @@ directory` setting (default `planning/`). 1. Read `NOW.md`, `config.md`, `ROADMAP.md`, and `STRATEGY.md` (focus milestone only). Read `STACK.md` when it exists and count its entries. - If `NOW.md` has a `Brief`, read its `## Decision` and - `## Open questions`. + Read `PAUSE.md` when it exists (Shared definitions: Pause file). If + `NOW.md` has a `Brief`, read its `## Decision` and `## Open questions`. 2. Count the open inbox (Shared definitions) and the inbox files with `Discuss: yes`. List briefs with `Status: shaping`. Count the **Uncommitted PM state** files for the `Note` section. @@ -88,14 +89,33 @@ directory` setting (default `planning/`). Handoffs table. - If a Spec, Plan, or Brief path is set but the file does not exist, add the Note: `Missing file: <path>.` -7. **For you:** collect, in this order, up to 5 of: the checkpoint's `Open - question`; `Owner: user` items in Next with `Status: ready`, in roadmap - order, flagging those that block agent items; `## Open questions` from briefs with `Status: - shaping`; the count of inbox files with `Discuss: yes`. -8. Show the output. Then ask one choice question: `Start "<next action>" +7. **Pause.** When the pause file exists: + - Its `Session` matches the current session: the pause's `Next action` + and `Start with` replace the next action from steps 5 and 6, unless + those made it `pm-rejoin`, which wins. Its `Open question` goes first + in "For you", and its `Context` lines go under "Decisions so far". + - Its `Session` is another branch: keep the next action from steps 5 + and 6 and add the Note `Paused on <Session> at <Paused>. To resume it: + git switch <Session>, then pm-resume.` Do not delete it. +8. **For you:** collect, in this order, up to 5 of: the pause's or the + checkpoint's `Open question`; `Owner: user` items in Next with + `Status: ready`, in roadmap order, flagging those that block agent + items; `## Open questions` from briefs with `Status: shaping`; the count + of inbox files with `Discuss: yes`. +9. Show the output. Then ask one choice question: `Start "<next action>" now?` with the options `Start it (recommended)` and `Show the board - first` (run `pm-board`). If a "For you" item blocks the next - action, put `Do <user item> first` as the recommended option instead. + first` (run `pm-board`, then ask again). If a "For you" item blocks the + next action, put `Do <user item> first` as the recommended option + instead. With a matching pause, the question is `Resume "<next action>" + from the pause of <Paused>?` with `Resume it (recommended)` and `Show + the board first`. +10. **Clear the pause.** When the user resumes a matching pause (`Resume + it`, or `Do <user item> first`), delete `<PM root>/PAUSE.md`, make one + PM commit (rules: Committing PM state) with `docs(pm): resume session + on <branch>`, and report it as a Note. Then start the pause's `Start + with`. This is the only file `pm-resume` writes. After compaction, the + silent resume in the Guard clears a matching pause the same way before + it continues the workflow step. ## Output @@ -107,6 +127,7 @@ directory` setting (default `planning/`). - Progress: <done>/<total> plan steps | no plan yet - Last checkpoint: <date time | none> - Stack: <n suspended | none> +- Paused: <YYYY-MM-DD HH:MM on <branch>, at <Running> | none> - Focus: <M Name | none set> ## Decisions so far @@ -125,5 +146,5 @@ directory` setting (default `planning/`). ## Note -- <only if needed: review due, inbox count, session mismatch, drift, uncommitted PM state, missing file> +- <only if needed: review due, inbox count, session mismatch, drift, uncommitted PM state, missing file, a pause on another branch, the pause-cleared commit> ``` diff --git a/skills/pm-setup/SKILL.md b/skills/pm-setup/SKILL.md index 245ee60..6a0211a 100644 --- a/skills/pm-setup/SKILL.md +++ b/skills/pm-setup/SKILL.md @@ -67,7 +67,7 @@ Collect these facts. Write nothing yet. 4. **Installed skills:** for each of `pm-init`, `pm-resume`, `pm-rejoin`, `pm-next`, `pm-up-next`, `pm-park`, `pm-bug`, `pm-risk`, `pm-shape`, `pm-discover`, `pm-strategy`, `pm-purview`, `pm-checkpoint`, - `pm-revise`, `pm-review`, `pm-item`, `pm-board`, `pm-roadmap`, + `pm-pause`, `pm-revise`, `pm-review`, `pm-item`, `pm-board`, `pm-roadmap`, `pm-status`, `pm-export`, `pm-docs-site`, and `pm-help`, check that a `SKILL.md` exists. - First run `npx skills list` (or `bunx skills list`), if either runs. @@ -142,7 +142,7 @@ questions. - Mode: install | upgrade v<old> to v<new> | repair (re-wrap the section) | reinstall (section missing, recorded v<n>) | already current (nothing to do) - Target: <file> (<append section | replace between markers | wrap the stranded section>) - Extra: <@AGENTS.md import added to CLAUDE.md | none> -- Skills: <n> of 23 installed. Missing: <names | none> +- Skills: <n> of 24 installed. Missing: <names | none> - Rules version: <v<n> recorded | not recorded | legacy v<n> in the marker | PM state not initialised> - Workflow framework: <Superpowers | name | partial | none> - Workflow skills: <n> of <total> installed. Missing: <names | none> @@ -258,7 +258,7 @@ Rules for this step: ## pm-setup done - Target: <file> (<installed | upgraded to v<n> | repaired>) -- Skills: <23 of 23 installed | missing: names> +- Skills: <24 of 24 installed | missing: names> - Workflow skills: <n of n installed | missing: names> - Rules version: <v<n> recorded in <PM root>/config.md | legacy v<n> migrated | PM state not initialised> - Diff check: only the managed section changed, plus the Rules version line and any added Commits settings @@ -270,7 +270,7 @@ Rules for this step: 1. <Only if skills are missing:> Install the missing skills. - Start with: `npx skills add https://github.com/purview-dev/pm-skills -y` - - Done when: all 23 pm-* skills are listed by `npx skills list` + - Done when: all 24 pm-* skills are listed by `npx skills list` 2. <Only if workflow skills are missing:> Install the workflow skills. - Start with: `npx skills add https://github.com/obra/superpowers -y`, or `/plugin install superpowers@claude-plugins-official` in Claude diff --git a/skills/pm-setup/references/AGENTS-section.md b/skills/pm-setup/references/AGENTS-section.md index c9c58d8..e5c2678 100644 --- a/skills/pm-setup/references/AGENTS-section.md +++ b/skills/pm-setup/references/AGENTS-section.md @@ -1,4 +1,4 @@ -<!-- pm-skills:start version=16 --> +<!-- pm-skills:start version=17 --> <!-- Managed by pm-setup. Edit outside these markers; content inside is replaced on upgrade. Installed copies keep this marker without a version. The version of record is `Rules version` in the PM root config.md, so editing or merging this file cannot lose it. --> @@ -21,7 +21,7 @@ repository root. | --- | --- | --- | | `pm-setup` | Install or upgrade these skills and this section | User asks | | `pm-init` | Create the PM root, write `VISION.md`, seed the roadmap | User asks | -| `pm-resume` | Show where work stopped and the next action for the agent and the user | Session start, after compaction, or user asks | +| `pm-resume` | Show where work stopped and the next action for the agent and the user; continue a pause and delete its file | Session start, after compaction, or user asks | | `pm-rejoin` | Find the true position in the lifecycle from git and PM state, then rejoin at the right stage | Drifted or detached from the lifecycle, NOW.md disagrees with the work, user asks "where am I" | | `pm-next` | Pick and claim the next claimable item on its own feature branch, hand off to design | No active item, user asks | | `pm-park` | Capture an idea, bug, question, or inspiration without derailing | Any time (capture mode only during a workflow) | @@ -32,6 +32,7 @@ repository root. | `pm-strategy` | Set vision, milestones, bets, and decisions; generate or re-plan the roadmap | User asks, or another PM skill recommends it | | `pm-purview` | Recommend Purview (purview.dev) .NET tools only where they add value; ask about stack and scale for new projects | User asks, or `pm-init`, `pm-discover`, `pm-shape`, `pm-strategy` find a .NET need it covers | | `pm-checkpoint` | Save state at a stopping point; suspend and resume an operation on the stack; close finished items on their branch | Session end, before compaction, stage end, user asks | +| `pm-pause` | Write the session's position (the step in progress, the open question, the next action) to the pause file, which `pm-resume` continues from and deletes | User asks to pause, including mid-workflow | | `pm-revise` | Correct work that is not what the user wanted: rewind the active item, fix it in place, or open a revision item | User asks, or a `Done when` check fails, including mid-workflow | | `pm-review` | Weekly triage of inbox and roadmap | User asks, or `pm-resume` says review is due | | `pm-item` | Add, edit, drop, block, unblock, move (including position), reassign, or complete one roadmap item | User asks | @@ -89,11 +90,17 @@ Every `pm-*` skill uses these definitions. The skills do not redefine them. merged. It is reversible: `pm-revise` (`fix-in-place`) removes the `## Done` line and restores `NOW.md` at `execute`, and the fix re-runs the finish order on the same pull request. -- **Reference legend:** the short list of the IDs a question uses, each with - the words needed to decide it: a milestone's name, whether it is the - focus, and the items in it; a roadmap item's title, owner, size, and - status; a risk's title, RAG, and status; a `V` line, bet, or inbox file's - one-line text. A question that names IDs prints it (Asking the user). +- **Reference legend:** the short list of the IDs a question or a + discussion uses, each with the words needed to decide it: a milestone's + name, whether it is the focus, and the items in it; a roadmap item's + title, owner, size, status, and section position (`Next 3`, `Later, M2`); + a risk's title, RAG, and status; a `V` line, bet, or inbox file's + one-line text. It lists every member of a range, not its ends: `M1 to + M4` lists M1, M2, M3, and M4, and `R-005 to R-010` lists every item + between them in roadmap order. A position (`before R-010`, `after M2`) + lists the item or milestone it names and its neighbours on each side, so + the user sees where the new position falls. It is printed first, before + the text that uses the IDs (Asking the user, Communication contract). - **Named reference:** an ID written with the words that identify it, so the user never has to look a bare ID up. In a list, board, roadmap, or status it is `<ID> <title>`; in a question, choice, or change line it is @@ -159,6 +166,16 @@ Every `pm-*` skill uses these definitions. The skills do not redefine them. does not export it. A **stack entry** holds the item, its `Done when`, the branch, the stage, the brief, spec, plan, milestone, started date, the reason it was suspended, and its checkpoint block. +- **Pause file:** `<PM root>/PAUSE.md`, the session's position written by + `pm-pause`: `Paused`, `Session` (a branch, matched like `NOW.md`), + `Item`, `Running` (the skill or workflow and its step), `Files`, the + uncommitted files outside the PM root, and a `## Resume with` block + (`Next action`, `Start with`, `Open question`) and `## Context`. It holds + one pause and points to the PM files that hold the decisions; it never + holds a decision only. Optional: a missing file means no pause. + `pm-resume` continues a pause whose `Session` matches and then deletes + the file, the one write `pm-resume` makes. It is session memory, so + `pm-export` does not export it. - **Bug:** an inbox file with `Kind: bug`, written by `pm-bug`, carrying `Severity`, `Affects`, and a `## Reproduction` block. It is triaged like any other inbox file (`pm-review`), shaped when the fix needs design @@ -394,6 +411,7 @@ might apply"). That rule does **not** apply to `pm-*` skills, except - as the item's completion step, after the execute stage passes its `Done when` checks and before the finish step pushes the branch (`pm-checkpoint`, `done` only), or + - when the user asks to pause the session (`pm-pause`), or - when the agent parks its own finding (`pm-park`, capture mode), or - when the user or the agent names a risk (`pm-risk`, capture mode). 3. **Mid-workflow, the only permitted PM writes are `pm-park` and @@ -417,10 +435,11 @@ might apply"). That rule does **not** apply to `pm-*` skills, except or reorder anything during a workflow. In every case the step in progress resumes afterwards. The PM write exceptions are rule 8 (`pm-revise`), rule 10 (`pm-checkpoint` push and pop), the stage update in - rule 2 (`pm-checkpoint` after a design or plan handoff), and the + rule 2 (`pm-checkpoint` after a design or plan handoff), the completion step in rule 2 (`pm-checkpoint` `done`, on the item's branch - before the finish step); rule 9 covers the docs site, which is not PM - state. + before the finish step), and `pm-pause` when the user asks to pause, + which ends the workflow at its step (rule 1) and writes the **Pause + file**; rule 9 covers the docs site, which is not PM state. 4. **If the user names another PM skill mid-workflow**, do not run it. Ask one choice question: `<skill> is at <step>. When should <pm-skill> run?` with the options `After <skill> finishes (recommended)` and `Pause now @@ -591,6 +610,9 @@ PM files are the only memory that survives compaction and new sessions. content contradicts the files, the files are correct. - Before a session ends, or when context is about to be compacted, with an item active, run `pm-checkpoint` (pause). +- When the user asks to pause the session, run `pm-pause`. It also covers + a PM operation or question in progress with no item active, and + `pm-resume` continues from its **Pause file**, then deletes it. ## Context budget (mandatory) @@ -856,6 +878,16 @@ search, and hand the write to a non-blocking background task when the agent has one, so the step in progress does not wait. `pm-review` runs the skipped `Related` search when it triages the file. No setting is added. +Version 17 shows referenced IDs first. Output that discusses `V` lines, +milestones, bets, or items prints a `## For this discussion` legend before +the text that names them, and every legend lists each member of a range +(`M1 to M4`) and the neighbours of a position (`after R-010`). Version 17 +also adds `pm-pause` and the **Pause file**: `pm-pause` writes the +session's position to `<PM root>/PAUSE.md`, and `pm-resume` continues from +it and deletes it. A missing file means no pause. From version 17 the +release major is the rules version, so every skills release is a rules +upgrade. No setting is added. + ## Asking the user (mandatory) - **Every question uses the agent's interactive question tool** (for @@ -875,8 +907,10 @@ skipped `Related` search when it triages the file. No setting is added. bet, `V` line, brief, or inbox file by ID alone. Print a `## For this question` legend (Communication contract) above the question, listing each ID it names with the words needed to decide it (Shared definitions: Reference - legend). Keep it to the IDs the question uses; do not print the whole - roadmap. + legend). A range lists every member and a position lists its neighbours, + so `Move R-005 after R-010?` and `Re-plan M1 to M4?` are never asked + without them. Keep it to the IDs the question uses; do not print the + whole roadmap. - **Offer a way to see more.** Add one escape option after the decision options; it does not count towards the 2 to 4 and is never an answer. `Explain <ID>` when the question names IDs, `Show the roadmap` for a @@ -920,6 +954,13 @@ Output must be literal, predictable, and immediately actionable. the plan, brief, or conversation. - Before a question that names IDs, print the `## For this question` legend (Asking the user). It is the only section a question adds. +- **Show before discussing.** When output discusses, compares, challenges, + or proposes a change to `V` lines, milestones, bets, or items (shaping, + strategy, review, reordering, re-planning) and names them by ID, print a + `## For this discussion` legend first (Shared definitions: Reference + legend), before any sentence that uses the IDs. One legend covers the + discussion; print it again only for IDs it does not list. A question in + the same output reuses it instead of adding `## For this question`. - At most 5 bullets per section, except boards, tables, and lists that a skill's template defines as complete. At most 3 sentences per paragraph. - State any assumption explicitly as `Assumption: ...`.