agent-pmo 0.1.0__tar.gz

agent_pmo-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+# Publishes agent-pmo to PyPI when a tag vX.Y.Z is pushed. PyPI trusted publishing: add this repository and the
+# workflow `release.yml` (environment `pypi`) as a trusted publisher of the agent-pmo project; no token is stored.
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: the tag, the package version and the changelog agree
+        run: |
+          version=$(python -c "import agent_pmo; print(agent_pmo.__version__)")
+          test "${GITHUB_REF_NAME}" = "v${version}" || { echo "tag ${GITHUB_REF_NAME} is not v${version}"; exit 1; }
+          grep -q "^## ${version} — [0-9]" CHANGELOG.md || { echo "CHANGELOG.md has no dated section for ${version}"; exit 1; }
+      - run: git config --global user.name ci && git config --global user.email ci@localhost
+      - run: python -m unittest discover -s tests
+      - run: python -m pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agent_pmo-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,43 @@
+name: tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.13"]
+        include:
+          - os: windows-latest  # not verified yet: kept visible without failing the build
+            python: "3.12"
+            experimental: true
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.experimental == true }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: git config --global user.name ci && git config --global user.email ci@localhost
+      - name: unit and end-to-end tests
+        run: python -m unittest discover -s tests
+      - name: the built wheel installs and runs
+        shell: bash
+        run: |
+          python -m pip install build
+          python -m build --wheel --outdir dist
+          python -m venv /tmp/venv-agent-pmo
+          /tmp/venv-agent-pmo/bin/pip install dist/*.whl || /tmp/venv-agent-pmo/Scripts/pip install dist/*.whl
+          export PATH="/tmp/venv-agent-pmo/bin:/tmp/venv-agent-pmo/Scripts:$PATH"
+          mkdir /tmp/project && cd /tmp/project && git init -q
+          agent-pmo --version
+          agent-pmo install --agents claude,agents
+          test -f .pm/WORKFLOW.md && test -f .pm/workflows/setup.md && test -f CLAUDE.md

agent_pmo-0.1.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# macOS Finder metadata
+.DS_Store

agent_pmo-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+The release notes of agent-pmo. `agent-pmo upgrade` prints the notes of every version a project moves past, so write
+each entry for the people upgrading: what changes for them, and anything they must do.
+
+Versions follow [semantic versioning](https://semver.org): a major version for changes that need the user or the agents
+to work differently, a minor version for new features, a patch version for fixes. Every change that needs a project's
+files moved or rewritten comes with a migration in `agent_pmo/kit.py`, which `upgrade` runs.
+
+## 0.1.0 — 2026-10-26
+
+The kit becomes the installable command `agent-pmo` (PyPI package `agent-pmo`).
+
+- **Install once per machine** with `pipx install agent-pmo` (or `uv tool install agent-pmo`), instead of copying the
+  kit into each repository. `python3 .pm/pm.py <command>` is now `agent-pmo <command>`.
+- **`.pm/` keeps only the agents' instructions** (WORKFLOW.md, workflows, best-practices files, docs). They are
+  generated: `agent-pmo install` writes them, `agent-pmo upgrade` refreshes them, and `agent-pmo check` reports edits.
+- **Each project pins its version** in `pm.toml` (`[kit] version`). Hooks, CI and the dev container install that
+  version. An older installed version refuses to run; a newer one warns until the project is upgraded.
+- **New commands:** `install`, `upgrade [--dry-run]`, `version [--check]`, and `--version`.
+- **Upgrading a project that copied the kit:** install agent-pmo, then run `agent-pmo upgrade` in the project. It
+  removes the copied code from `.pm/` (`pm.py`, `pmlib/`, `tests/`, `templates/`, the profile settings), drops the
+  secret-scan exceptions for it, rewrites the instructions, entry files, hooks and generated CI files, and pins 0.1.0.

agent_pmo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vikas Bhandary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_pmo-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: agent-pmo
+Version: 0.1.0
+Summary: Project management for AI coding agents: specs, decisions, tests, reviews and releases with traceable evidence.
+Project-URL: Homepage, https://github.com/vksbhandary/agent-pmo
+Project-URL: Changelog, https://github.com/vksbhandary/agent-pmo/blob/master/CHANGELOG.md
+Author: Vikas Bhandary
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,codex,project-management,specs,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# agent-pmo — project management for AI coding agents
+
+agent-pmo is a small command-line tool that lets coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, …) build a project the way a careful team would:
+
+- **Plan first, never guess.** Every open question is asked, and every answer is kept word for word as a decision.
+- **Work from specs.** Each component has a spec with requirements and a plan of small, testable increments.
+- **Prove each step.** Code is tested against its requirements, scanned for security issues, and reviewed by a *different* model.
+- **Keep you in charge.** Agents work in parallel and never wait. You review every unit in its own pull request, and `stable` only ever holds code that passed everything.
+- **Trace everything.** Every commit, report, issue and decision links back to the change and the requirement it belongs to.
+
+It works with any language, on Linux, macOS and Windows, with GitHub, GitLab, Bitbucket or no hosting at all. It needs Python 3.11+ and git, and has no dependencies of its own.
+
+## Set up
+
+```bash
+pipx install agent-pmo                       # or: uv tool install agent-pmo
+agent-pmo install --agents claude,agents     # in your repository: the agents' instructions and entry files
+```
+
+`install` writes the agents' instructions into `.pm/` and an entry file for each coding agent (`CLAUDE.md`, `AGENTS.md`; also `gemini`, `copilot`, `cursor`). Commit them with your project.
+
+Then open your coding agent in the repository and say one of:
+
+| | Say |
+|---|---|
+| New project | **"set up the project"** |
+| Existing code | **"analyse old code"** |
+| Idea in an issue | **"plan the project from issue #12"** |
+| Quick experiment | **"build `<idea>` quickly"** |
+
+The agent asks you everything it needs (what you're building, how you work, the coding style, your git provider) and sets up the rest. If you work with a git provider, give the agents their own token: `AGENT_TOKEN=<token>` in `.env`.
+
+## Day to day
+
+Talk to your agent: **"status"**, **"continue"**, **"test the next spec"**, **"review the next spec"**, **"fix `<bug>`"**, **"fetch repo issues"**, **"plan the deployment"**, **"revert `<change>`"**. You review and merge the review pull requests; CI does the rest.
+
+## Learn more
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | setup paths and the daily loop, in more detail |
+| [Commands](docs/commands.md) | every `agent-pmo` command with examples |
+| [Configuration](docs/configuration.md) | `pm.toml`, table by table |
+| [Concepts](docs/concepts.md) | units, statuses, the branch model, reviews, decisions, traceability |
+| [Automation](docs/automation.md) | hooks, CI, scheduled checks, providers and tokens |
+| [Development](docs/development.md) | the code map, tests, adding a language |
+| [WORKFLOW.md](WORKFLOW.md) | the process the agents follow (with one file per workflow in [workflows/](workflows/)) |
+
+## Updating
+
+Each project pins its version (`[kit] version` in `pm.toml`), so hooks, CI and the whole team run the same one. After `pipx upgrade agent-pmo`, run **`agent-pmo upgrade`** in the project: it migrates it, refreshes `.pm/`, the entry files, hooks and CI, and pins the new version. `agent-pmo version --check` shows what's installed, pinned and latest; [CHANGELOG.md](CHANGELOG.md) lists every release.

agent_pmo-0.1.0/README.md

@@ -0,0 +1,51 @@
+# agent-pmo — project management for AI coding agents
+
+agent-pmo is a small command-line tool that lets coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, …) build a project the way a careful team would:
+
+- **Plan first, never guess.** Every open question is asked, and every answer is kept word for word as a decision.
+- **Work from specs.** Each component has a spec with requirements and a plan of small, testable increments.
+- **Prove each step.** Code is tested against its requirements, scanned for security issues, and reviewed by a *different* model.
+- **Keep you in charge.** Agents work in parallel and never wait. You review every unit in its own pull request, and `stable` only ever holds code that passed everything.
+- **Trace everything.** Every commit, report, issue and decision links back to the change and the requirement it belongs to.
+
+It works with any language, on Linux, macOS and Windows, with GitHub, GitLab, Bitbucket or no hosting at all. It needs Python 3.11+ and git, and has no dependencies of its own.
+
+## Set up
+
+```bash
+pipx install agent-pmo                       # or: uv tool install agent-pmo
+agent-pmo install --agents claude,agents     # in your repository: the agents' instructions and entry files
+```
+
+`install` writes the agents' instructions into `.pm/` and an entry file for each coding agent (`CLAUDE.md`, `AGENTS.md`; also `gemini`, `copilot`, `cursor`). Commit them with your project.
+
+Then open your coding agent in the repository and say one of:
+
+| | Say |
+|---|---|
+| New project | **"set up the project"** |
+| Existing code | **"analyse old code"** |
+| Idea in an issue | **"plan the project from issue #12"** |
+| Quick experiment | **"build `<idea>` quickly"** |
+
+The agent asks you everything it needs (what you're building, how you work, the coding style, your git provider) and sets up the rest. If you work with a git provider, give the agents their own token: `AGENT_TOKEN=<token>` in `.env`.
+
+## Day to day
+
+Talk to your agent: **"status"**, **"continue"**, **"test the next spec"**, **"review the next spec"**, **"fix `<bug>`"**, **"fetch repo issues"**, **"plan the deployment"**, **"revert `<change>`"**. You review and merge the review pull requests; CI does the rest.
+
+## Learn more
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | setup paths and the daily loop, in more detail |
+| [Commands](docs/commands.md) | every `agent-pmo` command with examples |
+| [Configuration](docs/configuration.md) | `pm.toml`, table by table |
+| [Concepts](docs/concepts.md) | units, statuses, the branch model, reviews, decisions, traceability |
+| [Automation](docs/automation.md) | hooks, CI, scheduled checks, providers and tokens |
+| [Development](docs/development.md) | the code map, tests, adding a language |
+| [WORKFLOW.md](WORKFLOW.md) | the process the agents follow (with one file per workflow in [workflows/](workflows/)) |
+
+## Updating
+
+Each project pins its version (`[kit] version` in `pm.toml`), so hooks, CI and the whole team run the same one. After `pipx upgrade agent-pmo`, run **`agent-pmo upgrade`** in the project: it migrates it, refreshes `.pm/`, the entry files, hooks and CI, and pins the new version. `agent-pmo version --check` shows what's installed, pinned and latest; [CHANGELOG.md](CHANGELOG.md) lists every release.

agent_pmo-0.1.0/WORKFLOW.md

@@ -0,0 +1,159 @@
+# Workflow: how an AI coding agent works on this project
+
+This is the provider-neutral workflow of agent-pmo. `agent-pmo` is the command-line tool (Python ≥ 3.11); `.pm/` holds these instructions, generated by it. Any coding agent (Claude Code, Codex, Gemini CLI, Copilot, Cursor, …) follows it. Thin entry files such as `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.github/copilot-instructions.md` and `.cursor/rules/workflow.mdc` only point here; `agent-pmo init --agents …` generates them. Everything written about the project lives under `docs/`. Nothing in this file is project-specific: project settings are in `pm.toml`, and language rules are in the configured best-practices file (`.pm/profiles/<language>.md`).
+
+Run the kit with `agent-pmo <command>` (`--help` lists everything). Never edit generated content by hand: the index order, phase and status columns, the build-order lines, the module README header and contract blocks, and the `<!-- pm:begin … -->` blocks. Use `agent-pmo sync`.
+
+**The version:** the project uses the agent-pmo version in `pm.toml` (`[kit] version`). If `agent-pmo` is not installed, or a command or `agent-pmo check` reports a different version, stop and give the user the install command it prints (`pipx install agent-pmo==<version>`). Never edit `.pm/`: it is generated. Move the project to a newer version only when the user asks (`agent-pmo upgrade`).
+
+## 0. Is the project set up?
+
+If `pm.toml` does not exist, run **Project setup** ([workflows/setup.md](workflows/setup.md)) before anything else, unless the user asks for a one-off build ([workflows/oneoff.md](workflows/oneoff.md)), which needs no setup. If the repository already has code and commits, or the user asks to "analyse old code", adopt it first ([workflows/adopt.md](workflows/adopt.md)); with too little code, `agent-pmo adopt detect` sends you back to [workflows/setup.md](workflows/setup.md). After cloning an existing project, run `agent-pmo hooks install` so the git hooks are active.
+
+## 1. Where things are
+
+| What | Where |
+|---|---|
+| Project settings: language, ID prefix, review approval, risk, git strategy and branches, provider, coordination, hooks, schedule, container, gates, security tools | `pm.toml` |
+| Language best practices (follow them in all code and tests) | `.pm/profiles/<language>.md` |
+| Project guides: **agent guide (read it before your first unit)**, developer guide, project manager guide, and their changelog | `docs/guide/agent.md`, `docs/guide/developer.md`, `docs/guide/project-manager.md`, `docs/guide/changelog.md` |
+| **Coding style** for every file type (follow it in all code, tests, docs and config) | `docs/guide/coding-style.md`; enforced by `.editorconfig` and the linter/formatter configs generated from it |
+| Kit documentation: every command, the settings, the concepts | `.pm/docs/commands.md`, `.pm/docs/configuration.md`, `.pm/docs/concepts.md` |
+| Architecture, and its changelog | `docs/architecture/README.md`, `docs/architecture/changelog.md` |
+| Build order, dependency graph, module statuses | `docs/specifications/README.md` |
+| A component's spec (requirements, interface, implementation plan) | `docs/specifications/<component>/README.md` |
+| Its history, test plans and reports, review requests and code reviews | `docs/specifications/<component>/changelog.md`, `test/`, `review/` |
+| Change requests (new or updated requirements) | `docs/changes/` |
+| Decisions (question, the user's verbatim answer, why) and the assumption register | `docs/decisions/` |
+| Backlog: bugs, security and review findings, debt, accepted risks | `docs/backlog/` |
+| Security reports: per module, and project-wide | `docs/specifications/<component>/security/`, `docs/security/` |
+| Who is working on what (parallel agents), unique numbers | `agent-pmo claim list` (shared branch `pm/coord`) |
+| Developer summary of a module | `README.md` in the module's folder |
+
+If code and spec disagree, the spec wins, unless you deliberately change the spec in the same commit and give the reason in its changelog row. The agent guide adds project-specific rules for agents; where it conflicts with this workflow, this workflow wins and you tell the user.
+
+## 2. What the user says → what you do
+
+| User says | Workflow |
+|---|---|
+| "set up the project" / "start a new project" / "plan a project" | [workflows/setup.md](workflows/setup.md) Project setup: first the project discussion, then the settings |
+| "plan the project from issue #N" / "start from scratch with issue #N" (no `pm.toml` yet) | [workflows/discuss.md](workflows/discuss.md) Planning through an issue, kind `project` |
+| "take feature requests from the issues" / "plan the feature in issue #N" | [workflows/discuss.md](workflows/discuss.md) Planning through an issue, kind `feature` (`agent-pmo discuss candidates` lists the open feature requests) |
+| "analyse old code" / "analyse this repo" / "adopt the existing code" / "take over this codebase" (no `pm.toml` yet) | [workflows/adopt.md](workflows/adopt.md) Adopt an existing repository |
+| "build `<idea>` quickly" / "vibe code `<idea>`" / "one-off: `<idea>`" / "just build it, don't ask me much" | [workflows/oneoff.md](workflows/oneoff.md) One-off build: plan, implement and test on your own, then write REPORT.md. No setup, no git |
+| "implement the next spec" / "next" / "continue" | `agent-pmo next implement --claim`: a planned increment → [workflows/implement.md](workflows/implement.md); a backlog item (`FIX:`) → [workflows/fix.md](workflows/fix.md) |
+| "work in parallel" / several agents at once | [workflows/parallel.md](workflows/parallel.md): each agent claims its own module |
+| "set up the git provider" / "connect GitHub/GitLab/Bitbucket" (any phase) | `agent-pmo provider setup --kind …` after asking the user ([workflows/setup.md](workflows/setup.md) step 4); skippable |
+| "check the tokens" | `agent-pmo provider check` |
+| "use CodeRabbit" / "set up CodeRabbit" / "stop CodeRabbit" (any phase) | [workflows/setup.md](workflows/setup.md) (the CodeRabbit step): ask, then `agent-pmo coderabbit setup --mode …` |
+| Implementation is blocked by "coding style not agreed" | [workflows/setup.md](workflows/setup.md) step 6: first ask whether to use the languages' default styles, then the questions they want to decide |
+| "change the coding style" (all of it, a file type, or a rule) — at any time | `agent-pmo style change --types … / --ids … --reason "<user's words>"` opens the change (logged; nothing is blocked), then ask the questions now or later |
+| "answer the coding style questions" / "use the default style for X" | `agent-pmo style questions --pending`, ask them (some or all), then `agent-pmo style apply --answers …` (and/or `--defaults --question … --answer …`) |
+| A commit is refused for "no agreed coding style" or "differs from the agreed coding style" | A new kind of file: open a style change for its type (default or questions). A hand-edited style file: restore it, or go through a style change |
+| "test the next spec" | [workflows/test.md](workflows/test.md) Test (unit from `agent-pmo next test`) |
+| "review the next spec" | [workflows/review.md](workflows/review.md) Review (unit from `agent-pmo next review`) |
+| "approve the review" / "looks good" (on a review) | [workflows/review.md](workflows/review.md) step 9 |
+| A new feature, or a change to requirements or behaviour | [workflows/change-request.md](workflows/change-request.md) Change request: specs first |
+| The user answers a planning question, or changes an earlier decision | [workflows/planning.md](workflows/planning.md): record a decision (superseding the old one if needed) |
+| "what did we decide about X?" / "why is X like this?" | `agent-pmo decision list`, read the record(s), quote the user's answer and the reasoning |
+| A bug report, or "fix X" | `agent-pmo backlog new …` with a priority, then [workflows/fix.md](workflows/fix.md) |
+| "fetch repo issues" / "fetch the bugs" / "triage the issues" / "what's open on GitHub/GitLab/Bitbucket?" | [workflows/triage.md](workflows/triage.md) Issue triage |
+| "implement / test / review `<module>`" | The same workflow for that module's next increment. Refuse and show the blockers if its prerequisites aren't met. |
+| "security report" | [workflows/security.md](workflows/security.md) |
+| A scheduled-check summary arrives, or "run the scheduled checks" | [workflows/scheduled.md](workflows/scheduled.md) |
+| "land" / "land `<module>` increment `<k>`" / "open the PR" / a unit is AI-reviewed | `agent-pmo land …` ([workflows/review.md](workflows/review.md) step 10) |
+| "update my branch (from dev)" | `agent-pmo update-branch`, then report what it merged and what is left to resolve |
+| "make `<issue>` P1" / a priority change | `agent-pmo backlog priority BL-… P1` (or `unit priority` for an increment) |
+| "work without AI" / the user did work by hand | Read the guides' *Working without AI* sections; verify the hand-made documents (run the gates, regenerate incomplete reports), and point out gaps to the user instead of rewriting history |
+| "plan the deployment" / "how do we deploy?" / "change the deploy plan" | [workflows/deploy.md](workflows/deploy.md) Deploy plan |
+| "prepare a release" / "deploy `<version>` to `<env>`" / "roll back `<env>` to `<version>`" / "record the deployment" | [workflows/deploy.md](workflows/deploy.md) steps 5–8 |
+| "release" / "promote to staging/production" | [workflows/release.md](workflows/release.md) |
+| A merge conflict, or "merge X" | [workflows/merge.md](workflows/merge.md) |
+| "revert X" / "roll back" / "go back to the last stable version" | [workflows/revert.md](workflows/revert.md) |
+| "trace X" (a change, module, requirement, CR or backlog item) | `agent-pmo trace X`, then summarize |
+| "status" / "what's next?" | `agent-pmo status`, `agent-pmo backlog list --open`, then `agent-pmo next implement\|test\|review`, and summarize |
+| "check docs" | `agent-pmo check`, then fix what it reports |
+| "update agent-pmo" / "upgrade the kit" / "use the latest version" | `agent-pmo version --check`; the user installs the newer release (`pipx upgrade agent-pmo`), then `agent-pmo upgrade --dry-run`, show what changes, `agent-pmo upgrade`, `agent-pmo check`, and commit it as one change with its release notes in the message |
+| "add a rule/convention" / "update the guide(s)" | Edit the right guide in `docs/guide/` (developer, project manager or agent) and add a row to `docs/guide/changelog.md` in the same commit |
+
+Don't ask the user which unit to work on: `agent-pmo next` decides. If `next implement` is blocked because something is untested, say so and offer the test workflow. With other agents running, always pass `--claim` (and `--agent <id>` or set `PM_AGENT`), so two agents never take the same module.
+
+## 3. Units, priorities and statuses
+
+- **A unit** is one increment of one module, or one backlog item. Increments live in each spec's *Implementation plan*, each with `**Status:**`, `**Priority:**` and `**Also requires**`.
+- **Priorities:** `P0` (critical), `P1` (high), `P2` (normal, the default) and `P3` (low). They apply to increments (`agent-pmo unit priority <module> <k> P1`), change requests (`--priority`) and backlog items.
+- **Increment statuses:** `planned → coded → tested → reviewed`. Change them only with `agent-pmo unit set <module> <k> <status>`. It refuses `tested` without a filled-in PASS test report and test plan, and `reviewed` without enough approved independent reviews. It also re-syncs every place a status appears.
+- **Module status** is derived: `planned`, `coded`, `tested`, `reviewed` (some increments still planned) or `done` (all increments reviewed).
+- **Selection:** `next implement` takes every eligible unit and picks the highest priority. At equal priority, backlog fixes come before planned work, then phase and build order decide. Modules claimed by another agent are skipped. A planned increment is eligible when:
+  - earlier increments of the module are tested
+  - the index's *Depends on* modules have increment 1 tested
+  - everything in **Also requires** is tested
+  - earlier phases are tested **in the module and in the modules it depends on** (phase gate). Independent modules never wait for each other.
+  - no open P0/P1 backlog item exists for the module or a module it depends on. A bug blocks only its own module and its dependants.
+- `next test` picks the highest-priority `coded` increment; `next review` the highest-priority `tested` one, including units of other agents whose claim says `review-requested` (it prints the branch to check out).
+- **Formats are checked, not guessed:** a malformed increment heading, a missing `**Status:**` line, an unreadable *Also requires*, a malformed requirement ID or a duplicate module name is a `agent-pmo check` error. Nothing is skipped silently.
+- **Regression:** if a tested module's files change after its latest test report, `agent-pmo check` fails until a regression report is written ([workflows/implement.md](workflows/implement.md) step 5).
+
+## 4. Rules that apply everywhere
+
+- **Change IDs:** one per commit, from `agent-pmo change-id`. It reserves the ID on the shared coordination branch, so no other agent, branch or machine gets it. Every other number (DEC, AS, BL, CR, report files) is reserved the same way.
+- **Changelogs are for specifications and guides only:** a spec's `changelog.md`, the spec index (`docs/specifications/README.md`), the architecture's `docs/architecture/changelog.md`, and the guides' `docs/guide/changelog.md`. Never add changelogs to source code, module READMEs, instruction files or the kit; their history is the git log, linked to the change by `Change-Id` trailers.
+- **Docs never mention the kit:** everything under `docs/` is user-facing. Describe the flow and what to say to an agent, never `agent-pmo` commands or `.pm/` paths; the kit's own instructions stay in `.pm/`. `agent-pmo check` reports `docs/` files that mention the kit.
+- **Every guide change is logged:** a commit that changes the hand-written part of a guide in `docs/guide/` must add a row to `docs/guide/changelog.md`. `agent-pmo check` and the pre-commit hook enforce it. The settings tables `agent-pmo sync` regenerates need no row.
+- **A row only for a document that changed:** log a change only in the changelog of a spec, the index or the architecture that the same commit actually changes (for a folder's `changelog.md`: another file in that folder, such as the spec README or a new report). Process, kit and tooling changes get **no** changelog row — the commit and its trailers are their record. `agent-pmo changelog add` and the pre-commit hook refuse rows for unchanged documents. Add rows with `agent-pmo changelog add --id <ID> --summary "<what>" --reason "<why>" [--link <report>] FILE...`. Tables are newest first, with the latest 5 visible and older rows collapsed. `--link` attaches the test report, code review or security report the change produced. `agent-pmo check` rejects changelog tables anywhere else.
+- **Checks:**
+  - `agent-pmo check` must report `0 problem(s)` before every commit.
+  - The git hooks (`agent-pmo hooks install`) enforce this together with the secret scan and the configured gates. **Never use `--no-verify`.**
+  - If a hook blocks a commit, fix the cause.
+- **Code quality:** follow the language best-practices file, the spec's interfaces, and the module boundaries (only public interfaces of other modules). Keep the full test suite green.
+- **Tests are hermetic:** no network, no real external services, temporary directories.
+- **Reports are evidence:** fill in every `_(fill in)_` with real information, state plainly what was not verified, and never claim a pass you didn't run.
+- **Git:** follow the strategy in `pm.toml`. `agent-pmo land <module> <k>` lands a unit; `agent-pmo land-steps <branch>` explains what it does.
+  - `local`: fast-forward merge into the default branch, then `agent-pmo stable update` (moves `stable`, tags a rollback point), and never push unless the user asks.
+  - `pr` / `flow`, the branch model:
+    ```
+    unit branch ──agent PR──▶ dev ──▶ dev-<change id> ──user PR──▶ user-reviewed ──CI, all gates green──▶ stable
+    ```
+    Unit branches start from `dev`. After tests and the independent AI review, `agent-pmo land` opens the agent PR into `dev` and merges it as soon as CI allows: **agents never wait for the user**. Right after that merge it creates `dev-<change id>` and opens **the user's review PR** into `user-reviewed`. Its description lists possible issues, the changes made during the agentic review, the issues found, the evidence, and **the related review PRs in implementation order**: the PRs that depend on this one (they contain it; merge this first) and the earlier PRs it contains (merge those first), with module dependencies noted. `agent-pmo pr refresh` keeps those lists current; `land` and CI on `user-reviewed` run it. When the user merges it, CI runs every gate and fast-forwards `stable`, so `stable` always holds the last merged working code. `flow` then promotes `stable → staging → production`.
+  - Pushing unit and `dev-*` branches and opening labelled PRs is part of the agreed process. Never push to or merge into `dev`, `user-reviewed`, `stable`, staging or production directly (the pre-push hook blocks it), never merge a user PR yourself, and never force-push shared branches.
+  - Agents use their own account or token (a bot), not the user's: providers don't let a PR's author approve it, which is what makes the user's approval on `user-reviewed` real.
+- **Provider-neutral:** GitHub, GitLab and Bitbucket work the same way through `agent-pmo` (REST APIs, no provider CLI). The CI files come from `agent-pmo ci generate`. Never call a provider CLI or API directly for PRs, issues or labels.
+- **OS-neutral:** `agent-pmo` runs the same way on Linux, macOS and Windows. Its own commands never go through a shell. The generated commands are `agent-pmo …` on every OS; the configured gate commands are the only shell commands.
+- **Rollback is always possible:** never rewrite shared history (no `reset --hard` or force-push on shared branches). Undo means a revert commit ([workflows/revert.md](workflows/revert.md)).
+- **Missing tooling:** if a tool the gates need is missing, stop and tell the user the exact install command.
+
+## 5. Workflows
+
+Each workflow has its own file. **Before you start one, read its file in full; follow its steps in order; when it says so, finish with its check.** `agent-pmo workflow check …` verifies, from the evidence each step leaves (files, statuses, reports, decisions, commit trailers, claims), that no step was skipped; `agent-pmo workflow report` shows how well every unit followed its workflows. A failing check means a step is missing: do it, don't work around it.
+
+| Workflow | File | When | Finish with |
+|---|---|---|---|
+| Planning: zero assumptions | [workflows/planning.md](workflows/planning.md) | planning (setup, change requests, new specs, increments) | — |
+| Project setup | [workflows/setup.md](workflows/setup.md) | no pm.toml / "set up the project" | `agent-pmo workflow check setup` |
+| Implement | [workflows/implement.md](workflows/implement.md) | "implement the next spec" / "continue" | `agent-pmo workflow check implement --module M --increment K` |
+| Test | [workflows/test.md](workflows/test.md) | "test the next spec" | `agent-pmo workflow check test --module M --increment K` |
+| Review | [workflows/review.md](workflows/review.md) | "review the next spec", landing a reviewed unit | `agent-pmo workflow check review --module M --increment K` |
+| Change request | [workflows/change-request.md](workflows/change-request.md) | a new feature or a change to behaviour | `agent-pmo workflow check change-request --cr CR-NNNN` |
+| Security report | [workflows/security.md](workflows/security.md) | "security report", before a review | `agent-pmo workflow check security --module M` |
+| Release and promotion | [workflows/release.md](workflows/release.md) | "release", "promote to staging/production" | — |
+| Merge conflicts | [workflows/merge.md](workflows/merge.md) | a merge conflict, "merge X" | — |
+| Backlog fix | [workflows/fix.md](workflows/fix.md) | a bug report, "fix X", a FIX: unit | `agent-pmo workflow check fix --backlog BL-NNNN` |
+| Scheduled checks | [workflows/scheduled.md](workflows/scheduled.md) | a scheduled-check summary | — |
+| Revert and rollback | [workflows/revert.md](workflows/revert.md) | "revert X", "roll back" | — |
+| Parallel agents | [workflows/parallel.md](workflows/parallel.md) | several agents at once | — |
+| One-off build | [workflows/oneoff.md](workflows/oneoff.md) | "build X quickly", "vibe code X" | `agent-pmo workflow check oneoff --dir oneoff/NAME` |
+| Adopt an existing repository | [workflows/adopt.md](workflows/adopt.md) | "analyse old code" | `agent-pmo workflow check adopt` |
+| Issue triage | [workflows/triage.md](workflows/triage.md) | "fetch repo issues" | `agent-pmo workflow check triage` |
+| Planning through an issue | [workflows/discuss.md](workflows/discuss.md) | "plan the project / the feature in issue #N" | `agent-pmo workflow check discuss --issue N` |
+| Deploy plan | [workflows/deploy.md](workflows/deploy.md) | "plan the deployment", releases and deploys | `agent-pmo workflow check deploy` |
+
+## 6. Don'ts
+
+- Don't skip ahead of `agent-pmo next`, or combine several increments in one unit. Don't skip a workflow's steps, or report a workflow as done before its check passes. Don't work on a module another agent has claimed.
+- Don't add features beyond the increment's tasks. Put ideas in your report, propose a change request, or file a P3 backlog item.
+- Don't change a published interface without updating the specs of every module that uses it, with changelog reasons.
+- Don't mark anything with unrun or failing gates. Never approve on the user's behalf when approval needs the user. Never review a unit you implemented or tested.
+- Don't bypass hooks (`--no-verify`), force-push, or rewrite shared history.
+- Don't deploy to production, and don't keep production or deploy credentials on your machine.
+- Don't edit generated blocks, statuses, `.pm/`, or `pm.toml` choices the user made without asking.
+- Don't decide on the user's behalf during planning. Register the assumption and ask. Never edit an accepted decision record: supersede it.