From d6c049c5665c3fbadfc357b717b1c69c08165301 Mon Sep 17 00:00:00 2001 From: Kieron Lanning Date: Fri, 13 Nov 2026 19:12:50 +0000 Subject: [PATCH] feat: quick capture for pm-park and pm-risk mid-workflow Captures during a workflow classify from the words alone, skip the Related search (pm-review runs it at triage), and hand the write to a non-blocking background subagent when the agent has one, so the step in progress does not wait. Rules version 16. --- AGENTS.md | 31 +++++++++++++++++- package.json | 2 +- skills/pm-init/templates/config.md | 2 +- skills/pm-park/SKILL.md | 12 +++++-- skills/pm-review/SKILL.md | 6 +++- skills/pm-risk/SKILL.md | 10 ++++-- skills/pm-setup/references/AGENTS-section.md | 33 ++++++++++++++++++-- 7 files changed, 84 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a383031..aeb6629 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -392,6 +392,26 @@ Every `pm-*` skill uses these definitions. The skills do not redefine them. one, `RAG` always equals the derived value, and `pm-risk` recomputes it whenever Likelihood or Impact changes. `Status: accepted` and `closed` keep their RAG for the record. +- **Quick capture:** how `pm-park` (`capture`, `agent`) and `pm-risk` + (`capture`) write during an active workflow, so the step in progress + keeps its pace and its context. It never asks, never commits, and reads + no PM file the write does not need. + - **Fast path:** classify from the words alone. Take the active item ID + and stage from the session, not from `NOW.md`. Write `Related: none` + without searching; `pm-review` searches when it triages the file. A + risk reads only `RISKS.md`, for its new ID and RAG position, right + before it writes. + - **Background:** when the agent can start a subagent or background task + that does not block the turn (in Claude Code, the `Agent` tool), hand + it the words verbatim, the mode, `Source`, and the active item ID and + stage. Reply with the skill's background line and continue the step at + once; the task writes on the fast path and reports back only a + failure, which the agent prints as `Not saved: . `. + A subagent that blocks the turn is no faster, so without a non-blocking + one the fast path runs inline: one timestamp and one file write. Run + one background risk capture at a time, so two never take the same ID. + - A skill is never forked as a whole for this (for example `context: + fork`), because its other modes ask the user questions. - **Revision:** work that was built and is not what the user wanted. `pm-revise` records it in the brief's `## Revisions` and the `NOW.md` checkpoint while the item is open, or as a new roadmap item whose @@ -572,7 +592,10 @@ might apply"). That rule does **not** apply to `pm-*` skills, except then the exact step that was in progress resumes; `push` writes one stack entry, `pop` restores the top entry, and both reply in one line before the interrupted step resumes. No discussion, no evaluation, no - follow-up questions for any of them. If the user wants to discuss the + follow-up questions for any of them. `pm-park` and `pm-risk` run as a + **Quick capture** (Shared definitions), in the background when the + agent can. A capture the user types while the agent works is handled + between tool calls and never ends the step in progress. If the user wants to discuss the idea, set `Discuss: yes`; it is discussed later with `pm-shape`. A captured risk keeps `Reviewed: never` until `pm-risk` reviews it. The read-only exceptions: `pm-help` may answer a question about a skill in @@ -1016,6 +1039,12 @@ record. A session stays on its branch when the user asks, during an interruption, and while its pull request is pending. Every branch move pulls first, with `--ff-only`. No setting is added. +Version 16 adds **Quick capture**. During a workflow, `pm-park` and +`pm-risk` capture classify from the words alone, skip the `Related` +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. + ## Asking the user (mandatory) - **Every question uses the agent's interactive question tool** (for diff --git a/package.json b/package.json index ead2835..15be6e4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pm-skills", - "version": "0.12.0", + "version": "0.13.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/skills/pm-init/templates/config.md b/skills/pm-init/templates/config.md index 7350992..d3fb02c 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: 15 +- Rules version: 16 ## Handoffs diff --git a/skills/pm-park/SKILL.md b/skills/pm-park/SKILL.md index 5177bba..b810fc8 100644 --- a/skills/pm-park/SKILL.md +++ b/skills/pm-park/SKILL.md @@ -37,7 +37,10 @@ steps of the current plan. ## Steps 1. Note whether a workflow is active (Non-interruption rule 1). If one is, - this run is capture-only: no questions, no evaluation. + this run is a **Quick capture** (Shared definitions): no questions, no + evaluation, and no reads beyond the write. Hand it to a background task + when the agent has one; otherwise run steps 2 to 5 inline on the fast + path. 2. Classify without asking: - `Kind`: from the words used. Use `inspiration` for references, examples, or links with no stated feature; `question` for something to @@ -45,8 +48,10 @@ steps of the current plan. - `Discuss`: `yes` if the user asked to discuss, think through, or brainstorm it, or if it is a `question`; otherwise `no`. - `Related`: roadmap IDs and inbox titles that share the idea's key - nouns. Use `none` if nothing clearly matches. Do not ask. - - `Context`: the active item ID and stage from `NOW.md`, or `none`. + nouns. Use `none` if nothing clearly matches. Do not ask. During a + workflow, write `none` without searching (Quick capture). + - `Context`: the active item ID and stage, or `none`. During a workflow, + take it from the session; otherwise read it from `NOW.md`. 3. **capture** and **agent:** build the slug (lowercase ASCII letters, digits, and hyphens, at most 5 words). Get the timestamp (Shared definitions). The filename is @@ -65,6 +70,7 @@ steps of the current plan. matches, use `capture` mode and list the matches in `Related`. 5. Reply with exactly one line: - Workflow active: `Parked: (<, to discuss>). Back to .` + - Handed to a background task: `Parking "" (<kind><, to discuss>). Back to <current step>.` - `agent` mode: `Parked for later: <filename> (<kind>): <title>.` - No workflow: `Parked: <filename> (<kind>).` 6. If a workflow is active, resume the step that was in progress. Stop. diff --git a/skills/pm-review/SKILL.md b/skills/pm-review/SKILL.md index bca2318..72839de 100644 --- a/skills/pm-review/SKILL.md +++ b/skills/pm-review/SKILL.md @@ -42,7 +42,11 @@ root is its `PM state directory` setting (default `planning/`). the Challenge protocol checks 1, 2, and 5, state the result in one line, and ask one choice question: `What should happen to "<title>"?` with the proposed action first (recommended) and the next two most plausible - actions. Wait for the answer, then apply it before the next file: + actions. When the file has `Related: none` and a `Context` other than + `none` (a Quick capture skipped the search), grep `ROADMAP.md` and the + inbox for its key nouns first, and propose `Merge into <ID> <title>` + when one matches. Wait for the answer, then apply it before the next + file: - `Add to Next` or `Add to Later`: new roadmap item with a new ID (Shared definitions), `Serves`, `Milestone`, `Owner`, `Done when`, `Size`, `Depends on`, `Status: ready`, and the idea text in `Note:`. diff --git a/skills/pm-risk/SKILL.md b/skills/pm-risk/SKILL.md index b95909b..27cddb4 100644 --- a/skills/pm-risk/SKILL.md +++ b/skills/pm-risk/SKILL.md @@ -62,15 +62,18 @@ Whenever a question or reply names an ID, show `RK-NNN <title> (<RAG>)` or `R-NNN <title>` with it and add `Explain <ID>` to the question (Asking the user). -1. **capture:** classify without asking. +1. **capture:** during a workflow this is a **Quick capture** (Shared + definitions): hand it to a background task when the agent has one, + otherwise run it inline on the fast path. Classify without asking. - `Title`: at most 8 words from the user's words; keep their wording. - `Likelihood` and `Impact`: the levels the words state ("likely", "would lose data"); `medium` when they state none. - `RAG`: derived; `RAG override: none`. `Status: open`. - `Owner`: `user` when only the user can act on it (a decision, an account, a contract), otherwise `agent`. - - `Affects`: the active item ID from `NOW.md` when the risk is about it, - else the IDs, milestones, or paths the words name, else `none`. + - `Affects`: the active item ID when the risk is about it (from the + session during a workflow, else from `NOW.md`), else the IDs, + milestones, or paths the words name, else `none`. - `Trigger` and `Mitigation`: the words given, else `none`. - `Raised: <date> (<user | agent (<skill or item ID and stage>)>)`, `Reviewed: never`. @@ -78,6 +81,7 @@ user). Give it a new ID (Shared definitions: Risk IDs), insert it in `## Open` at its RAG position, and reply with exactly one line: - Workflow active: `Risk: RK-NNN <title> (<RAG>). Back to <current step>.` + - Handed to a background task: `Recording risk "<title>" (<RAG>). Back to <current step>.` - Otherwise: `Risk: RK-NNN <title> (<RAG>), unreviewed. Run pm-risk review RK-NNN to rate it.` If a workflow is active, resume the step that was in progress. Stop. diff --git a/skills/pm-setup/references/AGENTS-section.md b/skills/pm-setup/references/AGENTS-section.md index b3262af..c9c58d8 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=15 --> +<!-- pm-skills:start version=16 --> <!-- 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. --> @@ -203,6 +203,26 @@ Every `pm-*` skill uses these definitions. The skills do not redefine them. one, `RAG` always equals the derived value, and `pm-risk` recomputes it whenever Likelihood or Impact changes. `Status: accepted` and `closed` keep their RAG for the record. +- **Quick capture:** how `pm-park` (`capture`, `agent`) and `pm-risk` + (`capture`) write during an active workflow, so the step in progress + keeps its pace and its context. It never asks, never commits, and reads + no PM file the write does not need. + - **Fast path:** classify from the words alone. Take the active item ID + and stage from the session, not from `NOW.md`. Write `Related: none` + without searching; `pm-review` searches when it triages the file. A + risk reads only `RISKS.md`, for its new ID and RAG position, right + before it writes. + - **Background:** when the agent can start a subagent or background task + that does not block the turn (in Claude Code, the `Agent` tool), hand + it the words verbatim, the mode, `Source`, and the active item ID and + stage. Reply with the skill's background line and continue the step at + once; the task writes on the fast path and reports back only a + failure, which the agent prints as `Not saved: <reason>. <the words>`. + A subagent that blocks the turn is no faster, so without a non-blocking + one the fast path runs inline: one timestamp and one file write. Run + one background risk capture at a time, so two never take the same ID. + - A skill is never forked as a whole for this (for example `context: + fork`), because its other modes ask the user questions. - **Revision:** work that was built and is not what the user wanted. `pm-revise` records it in the brief's `## Revisions` and the `NOW.md` checkpoint while the item is open, or as a new roadmap item whose @@ -383,7 +403,10 @@ might apply"). That rule does **not** apply to `pm-*` skills, except then the exact step that was in progress resumes; `push` writes one stack entry, `pop` restores the top entry, and both reply in one line before the interrupted step resumes. No discussion, no evaluation, no - follow-up questions for any of them. If the user wants to discuss the + follow-up questions for any of them. `pm-park` and `pm-risk` run as a + **Quick capture** (Shared definitions), in the background when the + agent can. A capture the user types while the agent works is handled + between tool calls and never ends the step in progress. If the user wants to discuss the idea, set `Discuss: yes`; it is discussed later with `pm-shape`. A captured risk keeps `Reviewed: never` until `pm-risk` reviews it. The read-only exceptions: `pm-help` may answer a question about a skill in @@ -827,6 +850,12 @@ record. A session stays on its branch when the user asks, during an interruption, and while its pull request is pending. Every branch move pulls first, with `--ff-only`. No setting is added. +Version 16 adds **Quick capture**. During a workflow, `pm-park` and +`pm-risk` capture classify from the words alone, skip the `Related` +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. + ## Asking the user (mandatory) - **Every question uses the agent's interactive question tool** (for