# PM Skills

> Project-management skills that decide which feature an AI coding agent works on next.

Twenty-four agent skills that give a solo developer a parking lot, challenged shaping, strategy, a roadmap, a task board, a risk register, and memory across sessions — installed above a development workflow skill set such as Superpowers. They decide which feature is worked on; the workflow skills decide how it is built. Ideas are captured in one line at any time, shaped into a brief whose ramifications are challenged before they reach the roadmap, and every decision is written to a file as it is made so a compacted session can resume from it. The skills write only to the configured planning directory, commit only that directory, and create no branch except the item's own.

## Documentation version

- Channel: live (default)
- Source: purview-dev/pm-skills@main

## Resources

- Repository: https://github.com/purview-dev/pm-skills
- Project page: https://purview.dev/projects/pm-skills/
- Documentation: https://purview.dev/docs/pm-skills/
- Full machine-readable content: https://purview.dev/projects/pm-skills/llms-full.txt
- Concise machine-readable index: https://purview.dev/projects/pm-skills/llms.txt

Project-management skills for a solo developer using AI coding agents: they decide **which** feature is
worked on, and a development workflow skill set decides **how** it is built.

The skills sit above a workflow skill set, such as
[Superpowers](https://github.com/obra/superpowers). They are designed for
literal, predictable, low-friction output: one next action, an explicit
"done when", and fixed templates.

## What the skills do

- **Parking lot:** ideas, bugs, questions, and inspiration are captured in
  one line at any time, even mid-task, by you or the agent, and discussed
  later.
- **Bugs with the facts a fix needs:** `pm-bug` asks for the symptom,
  expected and actual, reproduction, severity, and evidence, checks for a
  duplicate, and routes the defect to a fix or the roadmap.
- **A risk register with RAG status:** `pm-risk` captures a risk in one
  line at any time, even mid-task, then adds, updates, re-rates, reviews,
  closes, or removes it in `planning/RISKS.md`. Each risk's red, amber, or
  green status is derived from its likelihood and impact, with a recorded
  override, and a mitigation can become a roadmap item.
- **Corrections, not pretences:** `pm-revise` handles built work that is not
  what you wanted. It rewinds the active item to an earlier stage, fixes it
  in place, or opens a revision item that revisits the original. It is the
  one PM skill allowed to interrupt an active workflow, and it writes the
  correction down first.
- **Brainstorming with challenge:** `pm-shape` interviews, challenges, and
  maps the ramifications of an idea before it reaches the roadmap.
  `pm-discover` analyses the existing code, history, and usage for
  evidence. Every idea, including the agent's own, is challenged.
- **Strategy, roadmap, and board:** `pm-strategy` sets milestones, bets,
  and focus, and generates the roadmap. `pm-roadmap` renders the full
  milestone roadmap, `pm-board` the task board, `pm-up-next` the ordered
  queue, and `pm-status` the summary and your own queue. Move, add, and
  insert items from the board or roadmap with the shared ordering rules.
  Items are owned by the agent, the user, or both.
- **The plan as data:** `pm-export` writes every roadmap item, board
  column, milestone, bug, brief, risk, and log entry to `planning/planning.json`
  in one fixed shape, with the JSON Schema that describes it, or checks the
  file without writing. The Markdown stays the source of truth.
- **The plan as a site:** `pm-docs-site` plans a local Astro and Starlight
  site that renders `planning.json` as Home, Board, Roadmap, Log, and Risks pages,
  then builds it from shipped templates inside that item's workflow.
  Optional modules add the repository's `docs/` pages, LikeC4 architecture
  views, and an Aspire AppHost resource. It reads the export only.
- **Purview fit:** for .NET projects, `pm-purview` recommends
  [Purview](https://purview.dev/) tools only where they remove real work.
  For an empty project it asks first what you are building and at what
  scale. Non-.NET projects get no suggestions.
- **Memory across sessions and compaction:** every decision is written to
  a file the moment it is made. `pm-resume` restores the state afterwards.
  `pm-rejoin` puts a session back on the lifecycle after the thread is
  lost. `pm-pause` saves the session's position, and `pm-resume` continues
  from it.
- **Commits without the chore:** the skill that writes the planning files
  commits them, on the branch you plan on; a completion record is committed
  on the item's branch so it rides the item's pull request. The default is
  automatic, set in `config.md` (`ask` or `never` instead), and the same
  commit refreshes `planning.json` when it exists.
- **Questions use the agent's question UI:** choices with a recommended
  option and free text. You are never asked to type `yes` or `a`/`b`/`c`.

## Where to go next

| Page | Answers |
| -- | -- |
| [Installation](guide/installation/) | How to install the skills and run them the first time |
| [The loop](guide/the-loop/) | How one item moves from claim to merge, and when every other skill runs |
| [Non-interruption guarantee](guide/non-interruption/) | What a PM skill may do during an active workflow |
| [Using a different workflow framework](guide/other-workflow-frameworks/) | How to hand off to something other than Superpowers |
| [Upgrading](guide/upgrading/) | How to update the skills and the shared rules |
| [Planning files](reference/planning-files/) | What `pm-init` creates and what each file holds |
| [Version history](reference/version-history/) | What each rules version changed |
| [Development](contributing/development/) | How to work on this repository |
| [Repository layout](contributing/repository-layout/) | Where each file lives |

Every skill, with its purpose and when it runs, is listed in the
[README](https://github.com/purview-dev/pm-skills/blob/main/README.md#skills).

---

How to install the skills and the workflow skill set they hand off to, then set up the planning files in
your repository.

Run this from the root of the target repository:

```bash
npx skills add https://github.com/purview-dev/pm-skills -y
# or
bunx skills add https://github.com/purview-dev/pm-skills -y
```

Skills install at project level by default. Add `-g` for a user-level
install, or `-a claude-code` to target a single agent. See the
[skills CLI](https://github.com/vercel-labs/skills) for all options.

## The workflow skill set

The skills hand design, planning, and execution to a workflow skill set,
by default [Superpowers](https://github.com/obra/superpowers). `pm-setup`
checks that every workflow skill is installed and prints the command when
one is missing:

```bash
npx skills add https://github.com/obra/superpowers -y
# or, in Claude Code
/plugin install superpowers@claude-plugins-official
```

To use another framework, see [Using a different workflow framework](../other-workflow-frameworks/).

## First run

Then, in your agent:

1. `run pm-setup` merges the rules into your existing `AGENTS.md` or
   `CLAUDE.md`, between `<!-- pm-skills:start -->` and
   `<!-- pm-skills:end -->` markers. Nothing outside the markers changes.
2. Commit, using the command `pm-setup` prints.
3. `run pm-init` writes `planning/VISION.md` by default and seeds the
   roadmap. `pm-setup` asks where to store the planning files before its
   other setup questions; choose a different repository-relative directory
   if needed.
4. Not sure what to run? `pm-help` explains every skill, lists what is
   missing in your setup, and recommends the next skill.

The files `pm-init` creates are listed in [Planning files](../../reference/planning-files/).

---

How the skills follow one item from claim to merge, which skills run outside that loop, and how ideas,
strategy, corrections, and data flow between them.

On purview.dev each diagram is an interactive LikeC4 sequence: select a step to read what the skill
reads, writes, and commits. Every diagram comes from one model,
[`pm-skills.c4`](https://github.com/purview-dev/pm-skills/blob/main/docs/wiki/diagrams/pm-skills.c4).

```likec4 view="index" title="The loop" description="One item from claim to merge" height="760"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Outside the loop

| Skill | When it runs |
| -- | -- |
| `pm-park` | Any time, capture only |
| `pm-review` | Weekly |
| `pm-risk` | Capture a risk any time; manage the register when no workflow is active |
| `pm-checkpoint` push/pop | Emergency suspension; the operation resumes at its checkpoint |
| `pm-shape`, `pm-discover`, `pm-strategy` | Think before building, no workflow active |
| `pm-item`, `pm-board`, `pm-roadmap`, `pm-status`, `pm-up-next` | On request, when no workflow is active (their read-only views also mid-workflow) |
| `pm-rejoin` | Any time the position is unclear; it hands back to the stage |
| `pm-bug` | A defect needs the facts a fix needs; it routes to a fix or the roadmap |
| `pm-revise` | Built work is wrong; it may interrupt to correct |
| `pm-export` | A tool needs the plan as JSON, or the export needs checking |
| `pm-docs-site` | Plan the site as an item; its build modes run in execute |

Captures, emergencies, and pauses during a workflow have their own diagrams in
[Non-interruption guarantee](../non-interruption/).

## Ideas

An idea reaches the roadmap in steps: `pm-park` (or `pm-discover`, or `pm-bug` for a defect) writes
the inbox, `pm-review` triages it, and `pm-shape` turns it into a brief and roadmap items. A defect can
skip the brief and become an item directly.

```likec4 view="ideasFlow" title="Ideas" description="From one line to a roadmap item" height="760"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Strategy

`pm-strategy` sets milestones and focus, then re-plans the roadmap so Next is ordered by the focus
milestone; `pm-board` renders that order.

```likec4 view="strategyFlow" title="Strategy" description="Milestones and focus to an ordered Next" height="640"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Corrections

`pm-revise` writes the correction to the brief's `## Revisions` (an open item) or opens a revision
item with `Revisits` (a done item), then hands back to the stage skill.

```likec4 view="reviseFlow" title="Corrections" description="Built work that is not what you wanted" height="560"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

When CI fails, the completion record is already in the pull request but not merged, so it is
reversible and the fix goes on the same pull request.

```likec4 view="ciFailure" title="CI fails on the item pull request" description="Fix it on the same pull request, never a new one" height="560"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Back on the loop

When a session loses its thread, `pm-rejoin` finds the true position from git and the planning files,
and repairs `NOW.md` only after you choose to rejoin.

```likec4 view="rejoinFlow" title="Rejoin" description="Back on the loop after the thread is lost" height="520"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Data

`pm-export` writes `planning/planning.json` from all of the above, and the `pm-docs-site` site renders
it: see [Planning files](../../reference/planning-files/#the-export).

---

What a PM skill may do while a development workflow is active, and the bounded set of writes and git
changes the skills make at all.

The merged rules make an active workflow own the session. During a
workflow, only `pm-park` and `pm-risk` may write, and only to capture, and
`pm-checkpoint` (`push`, `pop`) may write one stack entry to suspend or
resume the operation when you ask; `pm-rejoin` may
report the position, `pm-help` may explain a skill, `pm-export` and
`pm-docs-site` may check without writing, and `pm-status`, `pm-board`, `pm-roadmap`,
`pm-up-next`, and `pm-risk` may show their read-only view when you ask. None of them may
move, add, insert, or close anything mid-workflow. `pm-revise` may
interrupt to correct built work when you say it is wrong: it records the
scope and pauses the item before anything else runs.
Any other PM skill waits until the workflow finishes; the agent asks
whether to run it after the workflow or pause now.

On purview.dev each diagram below is an interactive LikeC4 sequence: select a step to read its notes.

## Capture mid-workflow

An idea or a risk typed while the agent works is captured in one line, in a background task when the
agent has one, and the step in progress resumes at once.

```likec4 view="quickCapture" title="Quick capture" description="Capture an idea or a risk mid-workflow" height="420"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Suspend for an emergency

`pm-checkpoint` `push` moves the active item onto `planning/STACK.md` so the session is free, and
`pop` restores it at its checkpoint, on the same branch.

```likec4 view="suspendResume" title="Suspend and restore" description="push frees the session; pop restores the item at its checkpoint" height="560"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## Pause the session

`pm-pause` writes the position to `planning/PAUSE.md`, with or without an active item, and the next
`pm-resume` continues from it and deletes it.

```likec4 view="pauseResume" title="Pause and resume" description="Pause the session and pick it up tomorrow" height="520"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## What the skills write

PM state skills write only to the configured planning directory (default
`planning/`), and never touch specs, plans, or code. A completion record is
the one PM write that happens outside the main worktree: the workflow runs
it at the end of the `execute` stage, and it is committed on the item's
branch so it rides the item's pull request, before CI runs.
The other exception is `pm-docs-site`'s build modes: the site is code, so
they run as a step of the site item's `execute` stage, on
its branch, and leave committing to the workflow.

## What the skills change in git

The git state changes they make are the commit of those planning files and
the branch moves of the feature-branch rules: `pm-next` pulls the latest
planning branch and starts each item on its own feature branch, and every
move pulls first with `--ff-only`. The session stays on its branch when you
ask, during an interruption, and while its pull request is pending. `pm-setup` edits only the managed section in the selected
agent instructions file, plus the `Rules version` line in `config.md`.

Full rules:
[`skills/pm-setup/references/AGENTS-section.md`](https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/references/AGENTS-section.md).

---

How to hand design, planning, and execution to a workflow skill set other than Superpowers.

Edit the Handoffs table in `<PM root>/config.md`. The skills refer to stages
(design, plan, execute, finish), not to Superpowers skill names.

---

How to update the installed skills and the rules they share, and how the skills remind you when the two
are out of step.

```bash
npx skills update
```

Then `run pm-setup` again. It replaces only the section between the
markers, which now carry no version, and records the new `Rules version` in
`config.md`; `pm-setup` reports when it is missing. An older marker that
still carries `version=N` is migrated on that run.

You do not have to remember the order. The next `pm-resume`, `pm-rejoin`,
or `pm-next` compares the rules version with the installed skills version
and asks before work resumes; `pm-help` reports the same finding.

```likec4 view="upgradeCheck" title="The upgrade check" description="Before work resumes, the rules and the skills are compared" height="600"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

The versions in the diagram are an example. On purview.dev, select a step to read what happens when
the versions are equal, the section is missing, or the skills are older than the rules.

What each version changed: [Version history](../../reference/version-history/).

---

The files `pm-init` creates in the PM root, what each one holds, and the derived export written beside
them.

The paths below use the default PM root; replace `planning/` with the
directory selected during `pm-setup`.

| File | Holds |
| --- | --- |
| `planning/config.md` | Handoffs to workflow skills, limits, commit policy, rules version, last review date |
| `planning/VISION.md` | v1 outcomes, out of scope, constraints |
| `planning/STRATEGY.md` | Focus, milestones, bets, assumptions, not doing, decisions |
| `planning/NOW.md` | The one active item, its checkpoint, decisions, and context |
| `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 |
| `planning/research/` | One `pm-discover` report per run |

Projects initialised before version 4 keep working. The new files are
created on first use; run `pm-strategy` to create `STRATEGY.md`.

## Which skill writes which file

```likec4 view="planningFiles" title="Planning files" description="Which skill writes which file, and what reads the export" height="760"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

## The export

`planning/planning.json` and `planning/planning.schema.json` are written by
`pm-export` on first use. They are derived from the files above: never
hand-edit them, and never treat them as the state. Once they exist, every
PM commit refreshes them first (`Export on commit` in `config.md`:
`if present` by default, or `always` or `never`).

```likec4 view="exportFlow" title="From a Markdown edit to the docs site" description="Every PM commit refreshes the export, so the site never lags the Markdown" height="600"
// One model for every pm-skills diagram. Each docs page renders one view;
// the dynamic views are sequence flows whose steps carry notes.

specification {
  element actor {
    style {
      shape person
    }
  }
  element skill {
    style {
      shape rectangle
    }
  }
  element stage {
    style {
      shape rectangle
      color secondary
    }
  }
  element folder {
    style {
      shape rectangle
      color slate
    }
  }
  element files {
    style {
      shape storage
      color amber
    }
  }
  element derived {
    style {
      shape storage
      color muted
    }
  }
  element delivery {
    style {
      shape rectangle
      color muted
    }
  }
  element site {
    style {
      shape browser
      color green
    }
  }
}

model {
  user = actor 'You' {
    description 'Starts sessions, has the ideas, answers the choice questions, and reviews the pull request'
  }

  // Lifecycle skills

  resume = skill 'pm-resume' {
    technology 'pm skill'
    description 'Reads the planning files and any pause, checks the rules version, and recommends one action'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-resume/SKILL.md
  }
  next = skill 'pm-next' {
    technology 'pm skill'
    description 'Challenges the first claimable item, moves to its feature branch, claims it, and hands off to design'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-next/SKILL.md
  }
  checkpoint = skill 'pm-checkpoint' {
    technology 'pm skill'
    description 'Records each stage, pauses, suspends and restores operations, and closes the item on its branch'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-checkpoint/SKILL.md
  }
  rejoin = skill 'pm-rejoin' {
    technology 'pm skill'
    description 'Locates the true position from git and PM state, then with consent repairs NOW.md and hands off'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-rejoin/SKILL.md
  }
  pause = skill 'pm-pause' {
    technology 'pm skill'
    description 'Writes the session position, with or without an active item, and commits it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-pause/SKILL.md
  }
  revise = skill 'pm-revise' {
    technology 'pm skill'
    description 'The one PM skill that may interrupt a workflow to correct built work; it writes the correction down first'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-revise/SKILL.md
  }

  // Capture and thinking skills

  park = skill 'pm-park' {
    technology 'pm skill'
    description 'Writes one inbox file and replies in one line, even mid-workflow'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-park/SKILL.md
  }
  bug = skill 'pm-bug' {
    technology 'pm skill'
    description 'Asks for symptom, expected and actual, reproduction, severity, and evidence, then routes the defect'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-bug/SKILL.md
  }
  risk = skill 'pm-risk' {
    technology 'pm skill'
    description 'Captures a risk in one line, or manages the register with RAG derived from likelihood and impact'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-risk/SKILL.md
  }
  background = skill 'background task' {
    technology 'subagent'
    description 'Writes a Quick capture on the fast path and reports back only a failure'
  }
  discover = skill 'pm-discover' {
    technology 'pm skill'
    description 'Analyses the code, history, and usage, writes a research report, and parks the chosen opportunities'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-discover/SKILL.md
  }
  shapeSkill = skill 'pm-shape' {
    technology 'pm skill'
    description 'Interviews, challenges, and maps the ramifications of one idea, then decides its outcome'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-shape/SKILL.md
  }
  review = skill 'pm-review' {
    technology 'pm skill'
    description 'Weekly triage: one inbox file at a time, then roadmap health and the Next order'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-review/SKILL.md
  }
  strategy = skill 'pm-strategy' {
    technology 'pm skill'
    description 'Owns vision, milestones, focus, bets, and roadmap generation; challenges every change'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-strategy/SKILL.md
  }

  // Edit, view, and data skills

  init = skill 'pm-init' {
    technology 'pm skill'
    description 'Creates the PM root, writes a challenged VISION.md, and seeds the roadmap'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-init/SKILL.md
  }
  setup = skill 'pm-setup' {
    technology 'pm skill'
    description 'Replaces only the managed section, records Rules version, and writes any setting the new version adds'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/SKILL.md
  }
  item = skill 'pm-item' {
    technology 'pm skill'
    description 'Adds, edits, drops, blocks, moves, reassigns, or completes one roadmap item'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-item/SKILL.md
  }
  board = skill 'pm-board' {
    technology 'pm skill'
    description 'The task board from Now to Done; moves, adds, inserts, or closes one card'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-board/SKILL.md
  }
  export = skill 'pm-export' {
    technology 'pm skill'
    description 'The only writer of planning.json and its schema, on request or as the refresh of a PM commit'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-export/SKILL.md
  }
  docsSite = skill 'pm-docs-site' {
    technology 'pm skill'
    description 'Plans the site as a roadmap item, builds it from templates in that item execute stage, and checks it'
    link https://github.com/purview-dev/pm-skills/blob/main/skills/pm-docs-site/SKILL.md
  }

  // Workflow stages, from the Handoffs table in planning/config.md

  design = stage 'design' {
    technology 'superpowers:brainstorming'
    description 'Writes the spec to docs/superpowers/specs/'
  }
  plan = stage 'plan' {
    technology 'superpowers:writing-plans'
    description 'Writes the plan to docs/superpowers/plans/'
  }
  execute = stage 'execute' {
    technology 'superpowers:subagent-driven-development'
    description 'Checks off the plan until every Done when check passes; owns the session while it runs'
  }
  finish = stage 'finish' {
    technology 'superpowers:finishing-a-development-branch'
    description 'Pushes the branch and opens the pull request'
  }

  // PM state

  pmRoot = folder 'planning/' {
    description 'The PM root in the main worktree: the state is Markdown, committed by the skill that writes it'

    config = files 'config.md' {
      description 'Handoffs, limits, commit policy, Rules version, last review'
    }
    vision = files 'VISION.md' {
      description 'v1 outcomes, out of scope, constraints'
    }
    strategyFile = files 'STRATEGY.md' {
      description 'Focus, milestones with exit criteria, bets, assumptions, Not doing, decisions'
    }
    now = files 'NOW.md' {
      description 'The one active item, its checkpoint, decisions, and context'
    }
    roadmap = files 'ROADMAP.md' {
      description 'Next (ordered, at most 5) and Later, grouped by milestone'
    }
    log = files 'LOG.md' {
      description 'Done, Dropped, Reviews'
    }
    stack = files 'STACK.md' {
      description 'Suspended operations, newest first, each with its stage, Done when, and checkpoint; not exported'
    }
    pauseFile = files 'PAUSE.md' {
      description 'The paused session position and a Resume with block; deleted once resumed; not exported'
    }
    risks = files 'RISKS.md' {
      description 'Open, closed, and removed risks with likelihood, impact, and RAG'
    }
    inbox = files 'inbox/' {
      description 'The parking lot: one file per idea, bug, or question'
    }
    briefs = files 'briefs/' {
      description 'One shaped idea per file: evidence, alternatives, challenges, ramifications, decision, revisions'
    }
    research = files 'research/' {
      description 'One pm-discover report per run'
    }
    json = derived 'planning.json + schema' {
      technology 'JSON Schema'
      description 'Derived: never hand-edited and never read as state; the Markdown wins when they disagree'
    }
  }

  // Outside the PM root

  agentFile = files 'AGENTS.md or CLAUDE.md' {
    technology 'Markdown'
    description 'The managed rules section between the pm-skills markers, which carry no version'
  }
  reference = files 'pm-setup reference' {
    technology 'AGENTS-section.md'
    description 'The skills version: N in the pm-skills:start version=N marker'
  }
  cli = skill 'skills CLI' {
    technology 'npx skills'
    description 'Installs and updates the skill folders; the agent never runs it for you'
  }
  branch = delivery 'item branch' {
    technology 'git'
    description 'feat/r-nnn-slug, created from the PM base; the claim and the completion record ride it'
  }
  pr = delivery 'one PR' {
    technology 'GitHub'
    description 'The single pull request for the item; a CI failure is fixed on the same one'
  }
  ci = delivery 'CI' {
    technology 'GitHub Actions'
    description 'Runs with the completion record already in the pull request'
  }
  main = delivery 'PM branch' {
    technology 'git'
    description 'main: the merge carries the code and the completion record together'
  }
  astro = site 'Docs site' {
    technology 'Astro + Starlight'
    description 'Home, Board, Roadmap, Log, and Risks pages, rendered from planning.json only'
  }

  // The loop

  user -> resume 'starts a session'
  resume -> pmRoot.now 'reads'
  resume -> pmRoot.pauseFile 'continues and deletes'
  resume -> next 'recommends'
  next -> pmRoot.roadmap 'claims from Next'
  next -> pmRoot.now 'writes the claim'
  next -> branch 'creates and switches to'
  next -> design 'hands off with the brief'
  design -> checkpoint 'spec written'
  plan -> checkpoint 'plan written'
  execute -> checkpoint 'Done when passes'
  checkpoint -> plan 'spec path'
  checkpoint -> execute 'plan path'
  checkpoint -> finish 'hands off'
  checkpoint -> pmRoot.now 'checkpoints, idles, restores'
  checkpoint -> pmRoot.log 'writes the Done line'
  checkpoint -> pmRoot.stack 'push and pop'
  checkpoint -> branch 'commits the completion record'
  finish -> pr 'pushes and opens'
  pr -> ci 'runs'
  ci -> main 'merge'

  // Ideas and strategy

  user -> park 'idea:'
  user -> bug 'add a bug'
  user -> risk 'risk:'
  park -> background 'hands the capture'
  risk -> background 'hands the capture'
  background -> pmRoot.inbox 'writes'
  park -> pmRoot.inbox 'writes one file'
  bug -> pmRoot.inbox 'writes Kind: bug'
  bug -> pmRoot.roadmap 'routes a fix'
  risk -> pmRoot.risks 'writes'
  discover -> pmRoot.research 'writes the report'
  discover -> pmRoot.inbox 'parks opportunities'
  review -> pmRoot.inbox 'triages'
  review -> pmRoot.roadmap 'adds and orders'
  review -> pmRoot.log 'logs the review'
  shapeSkill -> pmRoot.briefs 'writes after each answer'
  shapeSkill -> pmRoot.roadmap 'adds one item per slice'
  strategy -> pmRoot.vision 'revises'
  strategy -> pmRoot.strategyFile 'writes each approved section'
  strategy -> pmRoot.roadmap 're-plans'
  item -> pmRoot.roadmap 'edits one item'
  board -> pmRoot.roadmap 'renders and edits'

  // Corrections, pauses, and rejoining

  revise -> pmRoot.briefs 'writes Revisions'
  revise -> pmRoot.log 'removes an unmerged Done line'
  revise -> checkpoint 'pauses the item'
  revise -> execute 'hands back with the correction'
  pause -> pmRoot.pauseFile 'writes'
  pause -> pmRoot.now 'checkpoints'
  rejoin -> pmRoot.now 'repairs'
  rejoin -> execute 'hands off'

  // Setup, data, and the site

  init -> pmRoot.config 'creates'
  init -> pmRoot.vision 'writes'
  setup -> agentFile 'replaces the managed section'
  setup -> pmRoot.config 'records Rules version'
  user -> cli 'npx skills update'
  cli -> reference 'installs'
  export -> pmRoot.json 'writes'
  docsSite -> astro 'builds and checks'
  astro -> pmRoot.json 'reads'
}

views {

  // The default view: LikeC4 opens index first, and it is the first view declared.
  dynamic view index {
    title 'The loop: one item from claim to merge'
    description 'Select a step to read what the skill reads, writes, and commits.'
    variant sequence

    user -> resume 'starts a session' {
      notes '
        Run at session start or after compaction. pm-resume first compares
        `Rules version` in `planning/config.md` with the installed skills
        version, and asks to run pm-setup when they differ (see Upgrading).
      '
    }
    resume -> pmRoot.now 'reads NOW.md, ROADMAP.md, PAUSE.md' {
      notes 'Read-only. The files win over anything recalled from the conversation.'
    }
    resume -> user 'one next action: pm-next' {
      notes 'NOW.md is idle and the first item in Next is claimable, so the action is to claim it.'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'challenges the first claimable item' {
      notes '
        Claimable: in Next, `Status` ready or paused, owner agent or both,
        and every `Depends on` ID in Done. An item already claimed on
        another unmerged branch is skipped.
      '
    }
    next -> branch 'pull latest, switch -c feat/r-nnn-slug' {
      notes '
        The branch starts from the PM base: the remote PM branch, or the
        local one when it is ahead. A pull that is not a fast-forward stops.
      '
    }
    next -> pmRoot.now 'claims: NOW.md active, PM commit on the branch'
    next -> design 'hands off with the brief' {
      notes 'The handoff skill comes from the Handoffs table in planning/config.md.'
    }
    design -> checkpoint 'spec written' {
      notes 'Stage update only: the next stage reads the spec path, not the design conversation.'
    }
    checkpoint -> plan 'hands the spec path to plan'
    plan -> checkpoint 'plan written'
    checkpoint -> execute 'hands the plan path to execute'
    execute -> checkpoint 'every box checked, Done when passes' {
      notes 'pm-checkpoint `done` is the completion step, run before the finish step pushes.'
    }
    checkpoint -> branch 'commits docs(pm): close R-NNN slug' {
      notes '
        The completion record: the `## Done` line in LOG.md, NOW.md idle,
        the item removed from ROADMAP.md, and the brief set to done. It is
        built from the PM base, so it never reverts newer PM state.
      '
    }
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes the branch, opens one PR'
    pr -> ci 'runs with the record inside the PR' {
      notes 'A failure is fixed with pm-revise fix-in-place on the same pull request (view ciFailure).'
    }
    ci -> main 'merge carries the record to main'
    checkpoint -> user 'start a new session before the next pm-next' {
      notes 'One item per context: the next session reads the files, not this conversation.'
    }
  }

  dynamic view ideasFlow {
    title 'Ideas: from one line to a roadmap item'
    description 'Capture is cheap and never interrupts; triage and shaping happen later, when no workflow is active.'
    variant sequence

    user -> park 'idea: export the board as CSV' {
      notes '
        Capture only: classified from the words alone, no questions. During
        a workflow it runs as a Quick capture (view quickCapture).
      '
    }
    park -> pmRoot.inbox 'writes inbox/2026-11-14-0930-board-csv.md'
    park -> user 'Parked: board CSV export'
    user -> bug 'add a bug: the board drops paused items' {
      notes '
        pm-bug searches the inbox, roadmap, briefs, and log for a duplicate
        first. Mid-workflow it captures through pm-park with `Kind: bug`, and
        `pm-bug update` asks the questions later.
      '
    }
    bug -> pmRoot.inbox 'writes Kind: bug with Severity and Reproduction'
    bug -> pmRoot.roadmap 'blocker or major: adds the fix to Next' {
      notes '
        Severity drives the route: blocker is fixed before the active item
        continues, major and minor are scheduled, cosmetic is parked. The
        inbox file is deleted once the item carries every fact.
      '
    }
    user -> discover 'what do users struggle with?'
    discover -> pmRoot.research 'writes the research report as findings arrive'
    discover -> pmRoot.inbox 'parks the opportunities you chose'
    user -> review 'weekly review' {
      notes 'pm-resume reports a review as due after the review cadence (7 days), or when the open inbox reaches its threshold (10).'
    }
    review -> pmRoot.inbox 'triages one file at a time, bugs by severity first' {
      notes '
        Each file gets Challenge protocol checks 1, 2, and 5 and one
        question: Add to Next or Later, Merge into an item, Shape it, Keep it
        parked, or Drop it. A Quick capture skipped the Related search, so
        it runs here.
      '
    }
    review -> pmRoot.roadmap 'Add to Next: new R-NNN, inbox file deleted'
    review -> pmRoot.inbox 'Shape it: Discuss: yes'
    user -> shapeSkill 'shape the board CSV export'
    shapeSkill -> pmRoot.briefs 'writes the brief after every answer' {
      notes '
        Problem, evidence, at least three alternatives (do nothing, smallest,
        full), the full Challenge protocol, and a ramifications table. An L
        idea is sliced into S or M parts.
      '
    }
    shapeSkill -> pmRoot.roadmap 'Add to Next: one item per slice, Brief set' {
      notes 'The other outcomes are Build it now, Keep it parked, and Drop it (logged under Dropped in LOG.md).'
    }
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims it and hands the brief to design'
  }

  dynamic view strategyFlow {
    title 'Strategy: milestones and focus to an ordered Next'
    description 'Each section is written to STRATEGY.md as soon as it is approved, so a stopped session loses nothing.'
    variant sequence

    user -> strategy 'set the milestones and focus'
    strategy -> pmRoot.log 'reads V lines, throughput, inbox, research' {
      notes '
        Facts first: items done and open per V line and milestone, items done
        per week over 4 weeks, a forecast stated as an Assumption, and drift
        such as Next items outside the focus.
      '
    }
    strategy -> user 'Use these milestones? Focus on M1?' {
      notes 'A milestone legend is printed first, so no milestone is asked about by ID alone.'
    }
    user -> strategy 'Use them, focus on M1'
    strategy -> pmRoot.strategyFile 'writes milestones, focus, bets, Not doing' {
      notes '
        Each bet reads "We believe a change will produce a result for
        someone", with the signal that settles it. Every decision is
        appended to `## Decisions` with its reason and the rejected
        alternatives.
      '
    }
    strategy -> user 'Re-plan the roadmap for this strategy now?'
    user -> strategy 'Re-plan it'
    strategy -> pmRoot.roadmap 'proposes Next: focus, then dependency, then risk' {
      notes '
        Every item gets Serves, Milestone, Owner, Done when, Size, and
        Depends on. L items are split; user tasks that block agent items go
        first so they run in parallel.
      '
    }
    user -> strategy 'Accept this Next order'
    strategy -> pmRoot.roadmap 'rewrites ROADMAP.md, PM commit'
    user -> board 'show the board' {
      notes 'Read-only in view mode; a move, add, or insert asks one question, then commits.'
    }
    board -> pmRoot.roadmap 'renders Now, Next, For you, Waiting, Done'
    user -> next 'start the next item'
    next -> pmRoot.roadmap 'claims the first claimable item in Next'
  }

  dynamic view reviseFlow {
    title 'Corrections: built work that is not what you wanted'
    description 'The scope is written down before anything is changed, and the interrupted step never resumes silently.'
    variant sequence

    user -> revise 'the board should group by milestone, not owner' {
      notes '
        Mid-workflow this is the one PM skill allowed to interrupt
        (Non-interruption rule 8), and only when you name the wrong
        behaviour. A defect, rather than a change of intent, goes to pm-bug.
      '
    }
    revise -> pmRoot.briefs 'inspects: item, brief, spec, plan, checkbox counts' {
      notes 'Read-only. The evidence decides whether the mistake was in the spec, the plan, or the code.'
    }
    revise -> user 'What is wrong? Spec, plan, or code? How much is affected?'
    user -> revise 'the plan held, the code grouped by owner'
    revise -> pmRoot.briefs 'writes Revisions: wrong, Must now, Mode, Supersedes' {
      notes 'Each answer is written before the next question, so a compaction cannot lose the correction.'
    }
    revise -> user 'How should R-NNN be corrected?' {
      notes '
        rewind (a wrong spec or plan), fix-in-place (wrong code, the plan
        still holds), new item with Revisits (the original is done and
        merged), queue (still open in Next or Later), or park.
      '
    }
    user -> revise 'fix-in-place'
    revise -> checkpoint 'pause' {
      notes 'The checkpoint names the last step that still holds and the first step of the corrected work.'
    }
    checkpoint -> pmRoot.now 'checkpoint, docs(pm): revise R-NNN in place'
    revise -> execute 'hands back to execute with the revision' {
      notes 'The stage skill changes the spec, plan, or code; PM skills never do.'
    }
  }

  dynamic view ciFailure {
    title 'Corrections: CI fails on the item pull request'
    description 'The completion is unmerged, so it is reversible: fix it on the same pull request, never a new one.'
    variant sequence

    ci -> user 'CI fails on the pull request' {
      notes 'The completion record is already in the pull request, so the item is in Done on its branch only.'
    }
    user -> revise 'fix the failing build'
    revise -> pmRoot.log 'finds docs(pm): close R-NNN, removes the Done line' {
      notes 'An unmerged completion is the one case where a Done line is removed.'
    }
    revise -> pmRoot.now 'restores NOW.md from the parent commit, Stage: execute' {
      notes 'The branch stays the Session; no pm-checkpoint pause is needed here.'
    }
    revise -> execute 'hands back to execute with the failure'
    execute -> checkpoint 'boxes checked, Done when passes again'
    checkpoint -> branch 'writes the record again, docs(pm): close R-NNN slug'
    checkpoint -> finish 'hands off to the finish step'
    finish -> pr 'pushes to the same pull request'
    pr -> ci 'runs again'
  }

  dynamic view quickCapture {
    title 'Interruptions: capture an idea or a risk mid-workflow'
    description 'The step in progress keeps its pace: one line back, no questions, no commit.'
    variant sequence

    user -> execute 'execute is running step 4 of the plan'
    user -> park 'park this: the export needs a dry-run flag' {
      notes '
        Handled between tool calls; it never ends the step in progress.
        `risk: the CI runner may hit its quota` takes the same path through
        pm-risk capture.
      '
    }
    park -> background 'words verbatim, mode, Source, item and stage' {
      notes '
        In Claude Code this is the Agent tool. Without a non-blocking task
        the fast path runs inline: one timestamp and one file write. One
        background risk capture runs at a time, so two never take the same ID.
      '
    }
    park -> user 'Parking "export dry-run flag" (feature). Back to step 4.'
    park -> execute 'step 4 resumes at once'
    background -> pmRoot.inbox 'writes the file, Related: none, Context: R-NNN execute' {
      notes 'pm-review runs the skipped Related search when it triages the file. A failure is printed as Not saved.'
    }
  }

  dynamic view suspendResume {
    title 'Interruptions: suspend an item for an emergency'
    description 'push frees the session without losing the item; pop restores it at its checkpoint on the same branch.'
    variant sequence

    user -> checkpoint 'production is down: stack R-NNN' {
      notes 'push may run mid-workflow when you ask (Non-interruption rule 10). No branch is created or switched for the emergency.'
    }
    checkpoint -> pmRoot.stack 'writes the entry: branch, stage, Done when, checkpoint, reason'
    checkpoint -> pmRoot.now 'sets NOW.md idle, docs(pm): stack R-NNN'
    checkpoint -> user 'Stacked R-NNN at execute. Handle the emergency.'
    user -> execute 'fix the outage as its own operation' {
      notes 'Use pm-bug or pm-revise for its PM side; the emergency never skips Done when or a PM commit.'
    }
    execute -> user 'the fix is finished'
    user -> checkpoint 'pop' {
      notes 'pop runs only when no workflow is active. On another branch it asks before switching and pulling.'
    }
    checkpoint -> pmRoot.stack 'removes the top entry'
    checkpoint -> pmRoot.now 'restores the item, stage, and checkpoint'
    checkpoint -> execute 'hands off at the stage with its Next action'
  }

  dynamic view pauseResume {
    title 'Interruptions: pause the session and pick it up tomorrow'
    description 'The pause file points to the PM files that hold the decisions; it never holds a decision only.'
    variant sequence

    user -> pause 'pause here, I will pick this up tomorrow' {
      notes 'Works with or without an active item, including mid-workflow: the pause ends the workflow at its step.'
    }
    pause -> pmRoot.now 'checkpoints the active item' {
      notes 'Every decision from the session is written through to its brief, report, or STRATEGY.md first.'
    }
    pause -> pmRoot.pauseFile 'writes Running, Files, Next action, Open question'
    pause -> user 'Paused on feat/r-nnn-slug, docs(pm): pause session'
    user -> resume 'next session: where was I?'
    resume -> pmRoot.pauseFile 'Session matches: continues from Resume with' {
      notes 'A pause for another branch is reported, not continued.'
    }
    resume -> pmRoot.pauseFile 'deletes PAUSE.md' {
      notes 'The one write pm-resume makes.'
    }
    resume -> user 'Next action and the open question, verbatim'
  }

  dynamic view rejoinFlow {
    title 'Rejoin: back on the loop after the thread is lost'
    description 'locate is read-only and may run mid-workflow; repair runs only after you choose to rejoin.'
    variant sequence

    user -> rejoin 'where am I? NOW.md says idle' {
      notes 'The upgrade check runs first, as in pm-resume and pm-next.'
    }
    rejoin -> pmRoot.now 'reads NOW.md, ROADMAP.md, STACK.md, config.md'
    rejoin -> branch 'current branch, merged branches, spec, plan, recent changes' {
      notes 'git fetch, then git branch -a --merged against the remote PM branch. Nothing is written in locate.'
    }
    rejoin -> user 'Where you are: R-NNN unclaimed on feat/r-nnn-slug, at execute' {
      notes '
        One position from the evidence: recorded, moved, another session,
        completed, stacked, unclaimed, unplanned, unrecorded, or
        merged-unclosed. The stage comes from the plan: all boxes checked is
        finish, any unchecked is execute, a spec with no plan is plan.
      '
    }
    rejoin -> user 'Rejoin R-NNN at execute?'
    user -> rejoin 'Rejoin at execute'
    rejoin -> pmRoot.now 'repair: NOW.md active, checkpoint, docs(pm): rejoin' {
      notes '
        The item leaves Next in ROADMAP.md. A merged-unclosed item gets its
        late completion record on the PM branch instead: docs(pm): close
        R-NNN late.
      '
    }
    rejoin -> execute 'hands off with Done when and the Next action'
  }

  dynamic view upgradeCheck {
    title 'Upgrading: the check before work resumes'
    description 'The rules and the skills ship together, so a newer skill never runs against older rules without asking.'
    variant sequence

    user -> cli 'npx skills update' {
      notes 'Example versions: the skills are now v18, and the rules installed in this repository are still v17.'
    }
    cli -> reference 'installs the v18 skills'
    user -> resume 'start a session'
    resume -> pmRoot.config 'Rules version: 17'
    resume -> reference 'skills version: 18'
    resume -> agentFile 'start marker present' {
      notes '
        Equal versions continue. A missing marker or an unrecorded version
        asks to repair; a missing section stops, because the rules are not
        in the agent file. Skills older than the rules ask you to update them.
        pm-rejoin and pm-next run the same check.
      '
    }
    resume -> user 'Rules are v17, the skills are v18. Upgrade before continuing?' {
      notes 'Mid-workflow this question waits for the workflow to finish. pm-checkpoint and pm-park never run the check.'
    }
    user -> resume 'Run pm-setup now'
    resume -> setup 'runs pm-setup'
    setup -> agentFile 'replaces the managed section between the markers'
    setup -> pmRoot.config 'Rules version: 18, plus any new setting' {
      notes 'Version 5 added the Commits section and version 14 Export on commit; each missing setting is one question.'
    }
    resume -> user 'continues with the next action' {
      notes 'Continue on v17 instead records Upgrade debt: rules v17, skills v18 in the output Note.'
    }
  }

  dynamic view exportFlow {
    title 'Data: from a Markdown edit to the docs site'
    description 'The Markdown files are the state; every PM commit refreshes the export, so the site never lags them.'
    variant sequence

    user -> item 'add the board CSV export to Next'
    item -> pmRoot.roadmap 'writes R-NNN under Next' {
      notes 'Write-through: the edit is in the file before the reply.'
    }
    item -> export 'PM commit: refresh the export' {
      notes '
        Runs when `Export on commit` is always, or `if present` and
        planning.json exists, and a PM file other than the export changed.
      '
    }
    export -> pmRoot.roadmap 'reads every PM file except STACK.md and PAUSE.md'
    export -> pmRoot.json 'writes planning.json, copies the schema' {
      notes '
        Verified before the commit: valid JSON, the required keys in order,
        schemaVersion equal to the schema const, and NOW and Next matching
        the Markdown. A failure leaves the export as it was and is noted.
      '
    }
    item -> main 'docs(pm): add R-NNN board CSV export' {
      notes 'One commit per skill run, scoped to the PM root, on the PM branch, or on the item branch while one is active.'
    }
    user -> astro 'just docs'
    astro -> pmRoot.json 'reads planning.json' {
      notes 'A site whose SCHEMA_VERSION is older than the export schemaVersion fails its build until pm-docs-site upgrade runs.'
    }
    astro -> user 'Board, Roadmap, Log, and Risks pages'
    user -> docsSite 'is the site current?'
    docsSite -> astro 'check: templates, schema version, build' {
      notes 'Read-only. scaffold, extend, and upgrade run only in the execute stage of the site item (Non-interruption rule 9).'
    }
  }

  view loopOverview {
    title 'The loop: who talks to whom'
    description 'The skills, workflow stages, planning files, and delivery steps of one item.'
    include
      user, resume, next, checkpoint,
      design, plan, execute, finish,
      pmRoot.now, pmRoot.roadmap, pmRoot.log,
      branch, pr, ci, main
    autoLayout LeftRight
  }

  view planningFiles {
    title 'Planning files: which skill writes which file'
    description 'Every file in the PM root, the skills that write it, and the derived export the docs site reads.'
    include
      pmRoot,
      pmRoot.*,
      * -> pmRoot.*,
      astro,
      docsSite
    exclude user, background
    autoLayout LeftRight
  }
}
```

What each version added to these files: [Version history](../version-history/).

---

What each rules version changed for an installed project, from version 5 to version 13.

:::note
The upgrade notes for every version, including 14 and later, are kept in the managed rules:
[`skills/pm-setup/references/AGENTS-section.md`](https://github.com/purview-dev/pm-skills/blob/main/skills/pm-setup/references/AGENTS-section.md),
under *Upgrading before work resumes*.
:::

## Version 5

Version 5 adds the `Commits` section to `config.md`. Without it, a PM
commit asks before each commit and treats the main worktree's current
branch as the planning branch. Add the section to choose `always`, `ask`,
or `never`, and to name the branch.

Version 5 also adds the upgrade check. `pm-resume`, `pm-rejoin`, and
`pm-next` compare the installed rules version with the installed skills
version and offer `pm-setup` before any work resumes.

## Version 6

Version 6 moves that version of record out of the agent file: it is
`Rules version` in `planning/config.md`, so a merge, rewrite, or removed
marker in `AGENTS.md` cannot lose it. Installed markers therefore carry no
version, and `pm-setup` migrates an older `version=` marker into
`config.md` the next time it runs. If the section itself is dropped from
the agent file, the recorded version lets `pm-setup` reinstall or re-wrap
it instead of appending a second copy.

## Version 7

Version 7 splits the two views out of `pm-status`. `pm-board` owns the
task board, `pm-roadmap` owns the full milestone roadmap, and `pm-up-next`
shows the ordered queue without claiming anything. `pm-board`, `pm-roadmap`,
and `pm-item` can move, add, and insert items; the shared **Roadmap order
and edits** rules define positions, full-Next demotion, board-column
mapping, and confirmation. The read-only views may answer mid-workflow.
Done lines in `LOG.md` now record a `Milestone:` so roadmap progress can be
counted per milestone.

## Version 8

Version 8 makes every question show what it is about. A question that names
a milestone, item, bet, `V` line, or inbox file prints a
`## For this question` legend above it — each ID with the words needed to
decide it — and carries one escape option, `Explain <ID>`,
`Show the roadmap`, or `Show the board`, which prints the full block or runs
the read-only view and then asks the same question again. Neither the legend
nor the escape option changes state or counts as an answer.

## Version 9

Version 9 adds three skills and a derived state file. `pm-bug` logs a defect with
the facts a fix needs — symptom, expected and actual, reproduction,
severity, and evidence — in an inbox file with `Kind: bug`, then routes it
to a fix, the roadmap, shaping, or the parking lot. `pm-revise` corrects
work that is already built: it rewinds the active item to an earlier stage,
fixes it in place, or opens a revision item whose `Revisits` names the
original. It may interrupt an active workflow to correct it, and it records
the scope and pauses the item first. `pm-export` writes
`planning/planning.json` with `planning/planning.schema.json` in a fixed,
validated shape, or checks them without writing. Seed data comes from the
same files as before; bugs add `Severity`, `Affects`, and a
`## Reproduction` block to the inbox format, and revisions add an optional
`## Revisions` heading to a brief.

## Version 10

Version 10 adds `pm-docs-site` and Non-interruption rule 9. `plan` adds the
site, a module, or a page as a roadmap item; `check` compares an installed
site with the templates and the export, read-only, even mid-workflow; and
`scaffold`, `extend`, and `upgrade` build it inside that item's `execute`
stage. The site reads `planning/planning.json` only. When `pm-export`'s
`schemaVersion` moves, the site's build fails until `pm-docs-site upgrade`
runs, and `pm-help` reports the difference.

## Version 11

Version 11 makes completion ride the branch and adds the operation stack.
`pm-checkpoint` (`done`) writes the Completion record and commits it on the
item's branch, so the item's pull request carries it before CI runs; it is
never closed on the planning branch after the merge, and it never gets a
pull request of its own. When the last open item of a milestone closes, the
skill asks once and records the milestone as done in the same commit.
`pm-checkpoint` (`push`, `pop`) suspends and restores an operation through
`planning/STACK.md`, so an emergency never loses work and the interrupted
operation resumes at its checkpoint. `pm-rejoin` repairs a `merged-unclosed`
item whose completion missed its branch.

## Version 12

Version 12 adds the risk register and `pm-risk`. `planning/RISKS.md` holds
one block per risk with likelihood, impact, RAG, status, owner, trigger,
and mitigation; RAG is derived from likelihood × impact unless an override
records why. `pm-risk capture` may run mid-workflow like `pm-park`: it
writes one risk, replies in one line, and never commits. `pm-export` moves
to `schemaVersion` 3 with a `risks` key, and the docs site gains a Risks
page with a likelihood × impact matrix, a Red risks tile, and a Home list;
run `pm-docs-site upgrade` for an installed site.

## Version 13

Version 13 adds the context budget and named references. Each item is one
context: `pm-checkpoint` (`done`) tells you to start a new session (`/new`
or `/clear`) before `pm-next`, and a stage handoff passes the spec or plan
path instead of the conversation that produced it. Every skill prints an ID
with its title (`R-007 Tenant billing`) wherever its output names one, not
just the ID.

---

The tools and `just` recipes for working on this repository, and the versioning rules a pull request
must follow.

Requires [`bun`](https://bun.sh) and, for the git hooks,
[`lefthook`](https://lefthook.dev/installation) and
[`just`](https://github.com/casey/just).

- `just setup-skills` clears and re-links this repository's `skills/pm-*`
  into `.claude/skills/` and `.agents/skills/`, so the agents working here
  use the skills as they are being edited. `just setup-skills --cli` uses
  `bunx skills add ./ -y` instead, which copies them.
- `just validate` checks skill frontmatter, the README and managed-section
  tables, the `pm-setup` inventory, the section markers, the template
  placeholders, the export schema, the managed section installed in
  `AGENTS.md`, and that `docs-site/` still matches the `pm-docs-site`
  templates.
- `just docs` serves this repository's own project site (its plan from
  `planning/planning.json`, the README, these docs, and every skill) at
  <http://localhost:4321>; `just docs-check` tests, type-checks, and builds
  it.
- `just lint-check` runs `just validate` and lints all Markdown;
  `just lint-fix` applies Markdown fixes.
- `just install` verifies the tools and installs the git hooks (commitlint
  on commit, `just lint-check` 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.

## Versions and releases

- `just bump patch|minor|major` writes the next release version to
  `package.json`; `major` also raises the rules version.
- `just version-check` compares the version with `main` (also run on push).

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

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
`pm-help` skill guide; `just validate` fails otherwise. Full conventions are
in [`AGENTS.md`](https://github.com/purview-dev/pm-skills/blob/main/AGENTS.md).

Where each file lives: [Repository layout](../repository-layout/).

---

Where each skill, its references and templates, the scripts, and this repository's own planning state
and site live.

```text
skills/
  pm-setup/
    SKILL.md
    references/AGENTS-section.md
  pm-init/
    SKILL.md
    templates/
  pm-resume/SKILL.md
  pm-rejoin/SKILL.md
  pm-next/SKILL.md
  pm-up-next/SKILL.md
  pm-park/SKILL.md
  pm-bug/SKILL.md
  pm-risk/SKILL.md
  pm-shape/SKILL.md
  pm-discover/SKILL.md
  pm-strategy/SKILL.md
  pm-purview/
    SKILL.md
    references/catalogue.md
  pm-checkpoint/SKILL.md
  pm-pause/SKILL.md
  pm-revise/SKILL.md
  pm-review/SKILL.md
  pm-item/SKILL.md
  pm-board/SKILL.md
  pm-roadmap/SKILL.md
  pm-status/SKILL.md
  pm-export/
    SKILL.md
    references/planning.schema.json
    references/planning.example.json
  pm-docs-site/
    SKILL.md
    references/spec.md
    scripts/site.ts          renders a site from its manifest; write or check
    templates/site/          the core site (Astro, Starlight, plan pages)
    templates/repo-docs/     module: the repository's Markdown, read in place
    templates/architecture/  module: LikeC4 views through Astroc4
    templates/aspire/        module: the AppHost resource
  pm-help/SKILL.md
docs/wiki/                 this documentation, published on purview.dev
planning/                  this repository's own PM state
docs-site/                 this repository's own project site
scripts/
  validate.ts
  setup-skills.ts
  bump-version.ts
  check-version.ts
.github/
  copilot-instructions.md
  workflows/
    ci.yml
    release.yml
package.json
LICENSE.md
```