Skip to content

PMO Home

Jump to bottom
david pawloski edited this page Nov 2, 2026 · 1 revision

Welcome to the pmo wiki!

Project Management from within your project. For vibecoders.

Screenshot 2026-10-30 at 8 14 47 AM

Suggestions for further development:

  1. JIRA Integration
  2. Roadmap ranking
  3. Roadmap assignment/selection to/from team
  4. Beta/GA milestones/requirements
  5. Map effort/PtS to tokens/cost

Created by Pawloski.llc

Using PMO: agent and developer guide

The plan of record is packages/pmo/data/plan.json; the app that shows it is npm run dev:pmo (port 5199). Read it before changing anything.

"Implement step X.Y.Z"

  1. Run npm run pmo -- brief X.Y.Z. It prints, for that step: whether it can start, prerequisites, questions, git commands, environment, ports, services, the exact files you may change, guardrails, tasks, acceptance criteria and the commands that verify it.
  2. Ask the questions marked blocking, all in one message, and nothing else. Use each non-blocking question's default and list it as an assumption in the pull request.
  3. Run npm run pmo -- start X.Y.Z. It refuses to start if a prerequisite is incomplete, the tree is dirty, the step is already claimed by another branch, or Node is too old. It creates step/X.Y.Z-<slug> from an up-to-date main (add --worktree for a separate directory).
  4. Work inside the step's scope only. Commit as [X.Y.Z] summary.
  5. Finish: set the step to complete in plan.json with evidence (paths that exist) and completedAt, run npm run pmo -- check --for-pr, run the verification commands from the brief, push, and open a pull request using the checklist. Do this before reporting the task done (G-032).
  6. Any task, with or without a step: update the PMO before you say it is done. Work that has no step is not finished until a step exists; add it on a plan/<slug> branch (G-032).

Rules that are enforced

  • One step per branch. Branch names: step/<id>-<slug>, plan/<slug> (plan and docs only), release/<slug> (versions and integrity.lock.json only).
  • A step may change only the packages it lists, plus plan.json for its own step. Importing another package needs a declared dependency; relative imports may not leave the package (except src/contracts/**).
  • Frozen without a step that names them: packages/pilot-ui/**, tokens.css, integrity.lock.json, .env, package-lock.json.
  • Never commit directly to main. Hooks (npm run pmo:hooks) check locally and can be bypassed; the pmo-guard workflow is the check of record.
  • New functionality that needs configuration, keys, tokens, URLs or locations is added to packages/setup-orchestrator in the same change or in a step it names. Setup records secret references, never values, and says how a credential is rotated (G-031).
  • Every agent updates the PMO when a task ends: step status, evidence and completedAt in plan.json, or the follow-up added as a plan change, then npm run pmo -- check (G-032).
  • Foundational rules are in packages/pmo/data/guardrails.json (G-001 onward), each with its source document and how it is enforced.

Changing the plan

Add, re-scope or reorder steps on a plan/<slug> branch. The pmo plan commands do this without hand-editing plan.json: they validate the result, change only the text they name, and run only on a plan branch (--dry-run checks anywhere). Only roadmap steps can be changed or removed; ids, status and completion fields are never set this way. Every open step needs modules, effort, risk, value, acceptance criteria and, where relevant, questions, dependencies and environment. Run npm run pmo:validate after editing. When package structure changes, run npm run pmo:build and commit catalog.generated.json.

Commands

Command Purpose
npm run pmo -- status Progress by workstream
npm run pmo -- next Ready steps ranked by decision score
npm run pmo -- list --status roadmap Filter steps
npm run pmo -- brief <id> Everything needed to start a step
npm run pmo -- start <id> Create the step branch
npm run pmo -- check [--for-pr] Scope, imports, plan integrity, commits
npm run pmo -- plan template [step|epic|workstream] Print the skeleton of a new step, epic or workstream with the allowed values
npm run pmo -- plan add --epic <id> (--file step.json | --json '{...}') [--dry-run] Add a roadmap step to an epic; with no --file or --json, in a terminal, it asks for each field and confirms before writing
npm run pmo -- plan set <id> (--file changes.json | --json '{...}') [--dry-run] Change fields of a roadmap step; null removes a field
npm run pmo -- plan remove <id> [--dry-run] Remove a roadmap step that nothing depends on
npm run pmo -- plan epic --workstream <id> (--file epic.json | --json '{...}') [--dry-run] Add an epic with its first step
npm run pmo -- plan workstream (--file workstream.json | --json '{...}') [--dry-run] Add a workstream with its first epic and step
npm run pmo:validate Plan, guardrails and catalog freshness
npm run pmo -- agent setup Save the key for the Ask the PMO Agent window to .env.local (also agent status, agent prompt)
npm run pmo -- changes sync Read Jira feedback that a product owner approved into the local inbox (also list, show <KEY>, handoff <KEY> --step <id>)
npm run serve:feedback Start the gateway that files circled-screen feedback in Jira (setup in .env.example)

Jira feedback workflow (HEDFB)

packages/pmo/data/jira.json is the specification; npm run pmo:validate checks it against the names the code uses. Building the workflow on the Jira site is part of setup: packages/setup-orchestrator (src/feedback-workflow.js, src/feedback-adapter.js) lists it, asks the Jira admin to confirm it, and does not treat the connection as configured until they do. A test fails if it differs from jira.json. Change the workflow in both, in one step.

Transition From To Moved by
Create (start) New gateway
Start triage New Triage product owner
Ask reviewer Triage Needs Info product owner
Reviewer replied Needs Info Triage product owner
Approve Triage Approved for Build product owner
Decline New, Triage, Needs Info, Approved for Build Declined product owner
Hand off Approved for Build In Delivery PMO automation
Withdraw approval Approved for Build Triage product owner
Complete In Delivery Done PMO automation or product owner
Reopen Done, Declined Triage product owner
  • New issues start in New. There is no To Do status.
  • Approve needs the approval checklist and an approver who is not the reporter. Decline needs a comment giving the reason. Withdraw approval is blocked once the issue has the pmo-handed-off label.
  • The PMO moves an issue only by Hand off (pmo changes handoff), which looks the transition up by its target status, so Approved for Build must lead to In Delivery. In Delivery must never lead back to Approved for Build.
  • Nothing in Jira changes the repository; an approved change reaches main only through a plan step and a reviewed pull request.

CI and required checks

Every pull request runs pmo-guard (guard), the Node 20.19 / 22.12 / 24 quality matrix (quality), and the Gitleaks scan (secret-scan). Pushes to main also run quality and secret scanning. CI uses the compressed public catalog fixture in packages/pmo/test-data rather than requiring another local project.

Main protection must require guard, quality and secret-scan, one approving review, stale-review dismissal, code-owner review and no force pushes/deletion. GitHub currently rejects protection for this private repository with HTTP 403 (account capability); step 6.1.5 remains incomplete until the setting is enabled and verified. Workflow success alone does not prevent direct pushes.

Clone this wiki locally