# PMO as Code (full content) > The complete text of every page on https://pmoascode.com, generated at > build time from the same HTML readers see. The index version is /llms.txt. --- # Home URL: https://pmoascode.com/ A vendor-neutral standard · running live in three public deploymentsProject status is a build artifact. Charters, requirements, and risk registers live in Git as plain files. Every change is tested and gated before it merges, and the pipeline compiles the documents into status, roadmaps, and dashboards. Nobody types a status anywhere. It takes the Infrastructure-as-Code / GitOps playbook and points it at the PMO. See the artifact crosswalk →Quickstart The problem it answers ## The reporting is stale and the reasoning is lost. Today's PMO runs on PowerPoint, Excel, SharePoint, and email. Nothing is authoritative, and nobody records why decisions were made. Stale artifacts A deck is out of date the moment it's shared. RAG fiction Red, amber, and green are whatever the PM reports. Unauditable governance Approval is an email in an inbox no one can audit. An army of PMs It takes a team just to keep the decks current. 1Principles ## The five defaults. Declarative sources of truthoverhand-maintained artifacts Automation and auditovergates and approvals Traceabilityoverdense documentation Derived statusoverself-reported status Composable definitionsoverone-off, siloed tools The right-hand column is not banned. It is the exception, and exceptions get documented.Read the principles → Validation ## Declared, then checked. You author the document; the pipeline checks its fields, sections, and requirement links on every change. Watch it run: documents/PRJ-001-AUR/charter.md --- kind: charter project: PRJ-001-AUR id: AUR-charter status: approved --- ## Objective Cut onboarding from 14 days to under 2. ## Success Criteria - Onboarding p50 below 48 hours. docassert validate↻ run audit All checks passed frontmatter-schema · valid, all required sections present measurable-success-criteria · every criterion states a threshold risks-have-owner-and-mitigation · every risk names both clear to merge The checks decide what counts as done, the same way every time, and the same checks run for real in CI. Traceability ## Follow the thread: why does this test exist? The links carry the value. Documents stay thin and richly connected, so any test walks back to the business reason it exists. Test CaseAUR-TC-001 Complete the self-serve wizard → account active, zero support tickets. ↑ tests Acceptance CriterionAUR-AC-001 A new customer completes setup with no support ticket created. ↑ verifies Product RequirementAUR-PR-014 The product shall provide a self-serve onboarding flow. ↑ traces to Business RequirementAUR-BR-001 Reduce median customer onboarding time to under 2 days. ↑ which serves Charterobjective Cut customer onboarding from 14 days to 2. Five hops, no slide-hunting. The pipeline generates this walk from the links; it is the same graph behind the traceability matrix. (Aurora is the fictional sample project used in examples across this site; its people are invented. The deployments below are real.) From one document to a portfolio ## Every project has a unique ID and its own live page. Each project carries a stable identity, PRJ-001-AUR, that namespaces its documents (documents/PRJ-001-AUR/) and its items (AUR-BR-001). Nothing collides, and every item says which project it belongs to. The pipeline compiles all of it into a portfolio dashboard with a page per project. Each page opens on a verdict sentence built from that project's recorded causes, then shows its milestones, its risk matrix, and its features charted by dependency order and scope size. Hover any number and a tooltip explains where it came from. portfolio dashboard · illustrated● AMBER AUR Aurora — Customer Onboarding PRJ-001-AUR · 20 docs · 2 open risksAMBER ATL Atlas — Partner Portal PRJ-002-ATL · 5 docs · fully tracedGREEN PHX Phoenix — Support Response PRJ-004-PHX · charter · projectGREEN Each RAG is computed from that project's own documents, using coverage, open risks, and failing audits. The panel above shows the format; the live dashboard has today's states. See the live dashboard → Live proof ## The method is running in public right now. This site is ordinary hand-written web pages. The pipeline it describes runs in public, in three deployments that regenerate their dashboards and badges from their documents on every push. The meta-portfolio is PMO as Code governing its own development, Refuge for Humans is a real product spec converted from a Word BRD, and Aurora is the reference portfolio of disclosed-fiction samples. The meta-portfolio The portfolio that builds PMO as Code, run as PMO as Code: five real projects, every gate binding, ambers published. How it governs itself. Dashboard →  Repo → Reference portfolio Four sample projects, the gate on every pull request, a published traceability matrix. The badge above is the live derived status. Dashboard →  Repo → Refuge for Humans A real 14-section BRD converted faithfully, with its gaps on display. The case study covers what the audit found. Dashboard →  Repo → next → Why PMO as Code src/pages/index.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Why PMO as Code URL: https://pmoascode.com/why/ Why PMO as Code Why PMO as Code: the PowerPoint-and-email PMO fails. Today's PMO runs on PowerPoint, Excel, SharePoint, and email. Every artifact is stale by the time anyone reads it, and the approval trail lives in inboxes. ## Four tools and no source of truth. A portfolio runs across PowerPoint decks, Excel spreadsheets, SharePoint wikis, and approval email chains. The four never agree, none is authoritative, and each is somebody’s best guess at what was true last Thursday. PowerPoint Status decks updated weekly by a PM whose main job is finding numbers to put in the deck. Excel RAID logs, budget trackers, and roadmaps, each maintained by a different person with a different definition of current. SharePoint Charters, governance docs, and templates, mostly the version from the last project, lightly renamed. Email The approval chain lives here, in a thread where someone once said "looks good" and which nobody can find or audit now. ## Problem 1: stale on arrival. A deck takes hours to build. By the time it’s distributed, the schedule has slipped, the budget number has changed, and the risk that was escalated yesterday isn’t in it. The act of creating the artifact is the moment it becomes out of date. The staleness is built into the architecture. A hand-maintained artifact can only reflect what its author knew at save time, and nothing keeps it current because the data it summarizes lives somewhere else entirely. The cost Decisions are made on stale data, leaders steer by the deck while the portfolio drifts elsewhere, and the gap grows until a failure surfaces on its own. ## Problem 2: RAG is self-reported fiction. Every PM in the portfolio decides whether their project is green, amber, or red. The criteria are informal and the incentive is to stay green, so the dashboard stays green until something fails in public. Amber means whatever the PM wants it to mean this week, and red requires a difficult conversation. The system is least likely to produce the one signal that matters. What derived status does instead Status is computed from the documents themselves: whether every requirement traces to a test, which risks are open and who owns them, whether the approved documents still pass their audits, so the checks pick the color instead of a person. ## Problem 3: governance you can’t audit. A stage gate amounts to an email in which someone forwards a deck and someone else replies “approved.” Three months later, no one can find the thread, no one agrees on what was actually approved, and there’s no record of what conditions the approval was contingent on. When an auditor or a postmortem asks “who approved this, and under what conditions?”, the answer is “we think it was Dave, in an email, sometime in March.” Auditors know the difference between a record and a guess. What policy as code does instead A gate becomes a CI check that runs against defined criteria and records its result in the repository, and the approval becomes a merged pull request with a reviewer on record. The audit trail accumulates as a by-product of working. ## Problem 4: the army-of-PMs tax. In a mature portfolio, much of the PM headcount maintains the reporting layer above the projects. Someone collects status from each lead, and someone else turns it into slides for a meeting about the slides. None of this is project delivery. PMO as Code removes the collection step. Status is derived from the documents, so the reporting layer has nothing left to assemble, and the PM’s job returns to running the project. The reallocation The time formerly spent on reporting moves to delivery. One update to the document, and everything downstream regenerates from it. From the author ## Why I wrote this. My career began in development. I did some interesting things in the non-profit sector, corporate media, and then federal space. I eventually wound up kicking off a DevOps movement at the White House Communications Agency, before spending the next several years consulting with Fortune 500s around the world on their development practices. That path led me to a position over delivery modernization at Freddie Mac, and on to running my own company teaching others how to get on top of AI readiness. Now, I lead the PMO at a Fortune 200, and I bring a lot of expectations with me. In engineering, the truth always lives in the source. Every change is tested multiple times before it is deployed, and real-time monitoring shows the state of the whole as it truly is. Nobody ever has to ask the deployment how it feels about the way things are going. Stuff is either working or it isn't, and when done properly, the stuff not working never makes it out to the customer. Project and portfolio management, on the other hand, have always been much more subjective. Numbers are usually collected by hand, entered into a Gantt chart or pointed to a backlog, and invariably make their way into some status deck to hand off to leadership. The insights that may be garnered are usually out of date by the time anyone reviews them, and inaccuracy is almost treated as a feature. Why show red when green is such a more calming color, right? The automated development discipline I spent twenty years helping install around the world always seemed to stop just outside of the PMO's door. PMO as Code is an answer to that problem. If you view documents as the source for the PMO system, a lot of engineering practices and parallels begin to apply. Document pipelines can test every structural change just like code is unit tested. Modern LLMs can judge whether a requirement actually serves the goal it claims to, just like infrastructure monitoring judges a service against its thresholds. Project status can be derived from core documents the way a binary is built from code. And reconciliation loops keep the delivery boards converged with the documents, the same way GitOps keeps a cluster converged with its manifests. When something drifts, the system notices before I do. On my own portfolio, when an automation flags a project amber, the public dashboard says amber, and nobody gets to change it for a slide deck. The world going AI native is what makes this approach an urgent need instead of merely the right way to do things. AI-assisted delivery moves faster than any hand-assembled report can describe, so the choice is a reporting layer that compiles in seconds or outdated insights that were overtaken by events before they even got manually updated. Whether PMs will trade away their curated plans and polished decks for raw Git and Markdown is a question yet to be answered, but I'm providing the thoughts and tools necessary to get started for free right here, and all feedback is welcome. I'm keeping it all public and open: the tool and the standard are Apache 2.0, free to adopt if you choose. John Tanner ## What comes next. The principles name the five defaults behind the response, and the artifact crosswalk maps each problem to its as-code equivalent. The case study shows the whole approach against a real document set. Read the principles → The artifact crosswalk → The case study → ← previous Home next → Case study: Refuge src/content/pages/why.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Case study: Refuge URL: https://pmoascode.com/case-study/ A real conversion, with a public repo and a live dashboard, ambers includedCase study: a real Word BRD becomes a self-reporting project. Refuge for Humans is a real C4G product: a 14-section business requirements document written in Word. This is what happened when we ran it through the pipeline, including the parts that failed. Start here · Case study ## A dense, well-written BRD with invisible gaps. The document was good by Word-document standards: an executive summary, strategic goals, a success-metrics table, detailed signal specifications, NFRs, and a risk table, and its fourteen sections held real product thinking. What nobody could see from the prose was which requirements had no test, which risks had no owner, and what a reviewer would still need to chase down. terminal pip install "docassert[convert]" docassert extract "Refuge for Humans BRD.docx" # .docx → plain text, tables included The conversion ## Mapped faithfully, with nothing padded to pass. The doc-to-pmo skill split the BRD into a proper spine: a project anchor, charter, BRD, PRD, functional & non-functional requirements, a risk register, and test cases. At import that came to 49 traceable items, every reference resolving, all seven business requirements covered. The set has grown since; new scope arrives the same way everything else does here, through a pull request the gate re-checks. Where the source stated a threshold, it became a measurable criterion. Where it didn't, nothing was invented. documents/PRJ-001-RFH/brd.md (excerpt) - **RFH-BR-001**: The business shall block AI-generated posts before publication at a rate above 95% at steady state. - **RFH-BR-002**: The business shall keep false positives below 2% of genuine human posts. The findings ## The audit produced the PM's to-do list. Run the checks and the invisible gaps become named findings that describe the actual state of the spec: docassert validate · docassert status ✗ Missing required frontmatter: 'budget'; dates: 'target' # the BRD names neither✗ RFH-RISK-001…005 missing Probability, Impact, Owner # 5 risks, descriptions only🟠 product requirement covered by an acceptance criterion: 4/10 # six PRs untested No budget, no target date, no named sponsor The charter carries the gaps as TODOs. Nobody typed a plausible number to quiet the tool. 6 of 10 product requirements had no acceptance criterion Surfaced by the traceability graph in seconds; prose reviews reliably miss this kind of gap. The feedback loop ## The deployment improved the standard itself. The first audit blocked the draft charter for its missing budget, but "budget unknown yet" is a legitimate state for a draft. That tension went upstream the same day, into spec v0.2 and docassert 0.7.0, and the standard has distinguished integrity checks, which always block, from completeness checks, which are advisory for drafts and gate the moment a document is proposed. The finding came from real use and shipped back into the standard within a day. Live now ## See it running, ambers and all. The repo is public, the gate is binding, and the dashboard derives its status from the documents on every push. The badge below is live: it turns green when the work does, and no one can set it by hand. The live project page →The repo → The execution bridge ## Approved stories became a governed board. When the user stories were approved, the bridge scaffolded delivery in one pass. Ten product requirements became Feature issues, ten stories became sub-issues beneath them, and every item landed on a Projects board carrying its document id and project. The gate is real: draft stories never reach the board, and the whole structure regenerated idempotently on the second run. The scope guard proved itself the same day. A test issue titled "Add dark mode" was flagged scope:unverified within seconds of creation, with a comment pointing at the documents as the place scope changes actually happen. The project page now shows a Delivery panel reading from the board beside the document-derived status, and a Feature closes itself when its last story lands. The live dashboard →The issues → Do this to your documents One template click gives you the gate and the dashboard; one prompt lets Claude convert your existing Word docs the same way. Use the template →Quickstart with Claude Code → ← previous Why PMO as Code next → Runs on itself src/pages/case-study.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Runs on itself URL: https://pmoascode.com/self-governance/ Start hereThis standard governs its own development. The portfolio that builds PMO as Code is run as PMO as Code, in public. Every claim on this page is a link to the live artifact, so you can check rather than trust. ## The live portfolio. Three deployments derive their status from documents right now. The badges below are fetched live from each one; whatever they say is the current derivation, and this page has no say in it. The meta-portfolio Five projects govern the standard, the engine, the launch, and operations. The dashboard and each project page: GOV · ENG · STD · ADO · OPS Refuge for Humans A real project, converted from a Word BRD and governed end to end. Its live dashboard and the case study. The reference deployment Sample projects (the fictional Aurora set, disclosed as fiction) exercising every document kind. Its dashboard runs the same derivation as the real ones. ## The governing documents. The dashboards above are compiled from Markdown in a public repository. The sources are one click deep: documents/ → Charters, requirements, risk registers, test cases, and status reports for all five projects, each validated on every change. projects.yaml → The project registry, generated from the anchor documents. A CI check fails if it goes stale. STATUS.md → The derived status summary committed alongside the sources, with its own staleness gate. The operations runbook → Recurring procedures as a governed document: numbered steps, changed only by pull request. ## The gates, observable. Every document change to the portfolio passes the same gate this site tells you to build, and the runs are public. The Actions history shows every audit; branch protection blocks a merge whose checks fail, whoever authored it. One complete chain, followable end to end: the scope for this site's rewrite was approved by merging a documents pull request, the merge scaffolded the delivery stories within seconds, the delivery pull request closed the stories on merge, and the features closed themselves when their last story did. ## The colors are derived. Whatever color the checks derive at build time is the color the dashboards show. A project lead can flag a concern and pull a color down; nothing anyone types can turn a failing derivation green. If a project page shows amber when you open it, that is the state of the checks, published anyway. The rules of that derivation have their own explainer: derived status over self-reported status. ## Measured adoption. Adoption is counted, never estimated, and published from day zero, small numbers included. This section regenerates on every deploy and at least monthly. 0 template forks Public forks of the starter template, via the GitHub API. Repos generated from the template (rather than forked) are not exposed by any API, so this undercounts by design and says so. 0 engine forks · 0 stars Forks and stars of the docassert repository, via the GitHub API. Dependents are not exposed by an API and are not guessed at here. 10,933 PyPI downloads in the last 30 days Via pypistats.org, where the live number is always visible. Downloads include mirrors and CI runs; this is a distribution signal, and it is deliberately not called an adopter count. Measured 2026-08-01. ← previous Case study: Refuge next → Principles src/pages/self-governance.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Principles URL: https://pmoascode.com/principles/ 1Layer 1 · PrinciplesPrinciples: the five defaults of PMO as Code. The layer that rarely changes and is owned by no one: what the standard defaults to, and what needs a documented reason to deviate. Default over exception Declarative sources of truthoverhand-maintained artifacts Automation and auditovergates and approvals Traceabilityoverdense documentation Derived statusoverself-reported status Composable definitionsoverone-off, siloed tools The right-hand column is not banned. It is the exception, and exceptions get documented. ## Every default gets its own explainer. In the order they appear above. 01 · explainer Declarative sources of truth over hand-maintained artifacts Declare once; the matrix, the dashboards, and the registry become build outputs. Read → 02 · explainer Automation & audit over gates & approvals The posture shifts from prevention to flow, and the gate becomes policy as code. Read → 03 · explainer Traceability over dense documentation Value lives in the links between thin, richly connected artifacts. Read → 04 · explainer Derived status over self-reported status Nobody types a color. Every verdict names its causes, and people can only pull a color down. Read → 05 · explainer Composable definitions over one-off, siloed tools One grammar across every kind; profiles bundle kinds; a new kind is data, mostly. Read → ## Three layers, each clearly owned. The structure keeps strong opinions and open implementation from blurring together, so a reader always knows which layer they're standing on. 1 Principles Five defaults · rarely changes · owned by no one. 2 The Reference Approach Our opinionated implementation: document model, kinds, checks · versioned · maintained by John Tanner at C4G. 3 Profiles Named bundles others compose or fork: regulated-industry, lean-startup, agile-delivery · independent · owned by the community. The standard is written down Layer 2 is a versioned specification with conformance language, precise grammars, and blocking semantics. Anyone can implement it; docassert is the reference implementation.Read the specification → The author statement, Why I wrote this, now lives on Why PMO as Code. ← previous Runs on itself next → Declarative sources of truth src/pages/principles/index.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Declarative sources of truth URL: https://pmoascode.com/principles/declarative/ 1Layer 1 · Principles · Explainer 01Declarative sources of truth over hand-maintained artifacts. A declarative source states what is true in one authoritative place. A hand-maintained artifact restates it, and the two begin to disagree the moment the copy is saved. ## The shift: declare once, converge everywhere. Infrastructure as Code settled this argument for servers years ago: you declare the state you want, and tooling makes the world match. PMO as Code applies the same posture to the portfolio. The documents declare what is true, and every other surface is computed from them. Frontmatter declares a document's identity, status, and dates. Items declare the requirements, risks, and tests. Typed links declare the reasoning between them. None of it is prose that a reader must interpret; all of it is structure that a pipeline can check. documents/PRJ-001-AUR/charter.md # frontmatter declares; nothing downstream is typed by hand id: AUR-charter kind: charter project: PRJ-001-AUR status: approved dates: target: 2026-12-31 ## Everything else derives. Once the sources are declarative, the artifacts people used to maintain become build outputs. Each of these is live in the reference deployments today: The traceability matrix Regenerated from the link graph on every change. Nobody reconciles a spreadsheet against the requirements. Status pages and RAG Computed from the documents and their check results, rebuilt when the documents change. The project registry Generated from each project's anchor document, with a CI job that fails if the registry goes stale. This site's metadata Page dates come from git history at build time, and the sitemap and llms.txt are generated from the same records that render the pages. ## Where hand-made artifacts still belong. Judgment is authored, and it should be. A charter's objective, a risk's mitigation, a post-implementation review's lessons: people write those, in the documents, where the history lives. When a deck is required anyway Some forums demand a slide. Make it an export of the sources, dated, and treat it as a snapshot. The failure mode this principle exists to prevent is the copy becoming the place where truth gets edited. ← previous Principles next → Automation & audit src/pages/principles/declarative.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Automation & audit URL: https://pmoascode.com/principles/automation/ 1Layer 1 · Principles · Explainer 02Automation and audit over gates and approvals. A gate assumes people will misbehave unless someone blocks them. Audit starts from good faith and relies on the record to keep everyone accountable. ## The shift: from prevention to flow. A gate puts a human in the loop who must approve before work proceeds. It slows the work and fills an inbox with decisions that no one can audit later, and the default posture becomes stop until told otherwise. Audit inverts that default. Every change and every decision lands in Git history, the record supplies the accountability, and the work keeps moving. Gates An approval email in an inbox that nobody can audit later. The default is stop. Audit Git history and merged pull requests, with every decision traceable. The default is flow. ## The gate becomes policy as code. The gate becomes an automated, auditable check that runs in CI, and the result lands in the repository's history alongside the change it judged. .github/workflows/audit.yml on: [pull_request] jobs: audit: # validate each changed document steps: - { uses: actions/checkout@v4, with: { fetch-depth: 0 } } - uses: c4g-john/docassert-action@v1 with: { command: validate, changed-only: 'true' } consistency: # broken traces block the merge steps: - { uses: actions/checkout@v4 } - uses: c4g-john/docassert-action@v1 with: { command: consistency } ## Where gates still belong. Some contexts legally require a person's signature, and the framework accommodates them. A human approval stays available for the cases that need one, as a documented exception. When a human signature is required Model it explicitly with branch protection that requires a named reviewer on the pull request. The approval lands in the merge record with the rest of the history, and one of the gate's signals is now a person's explicit sign-off. ← previous Declarative sources of truth next → Traceability src/pages/principles/automation.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Traceability URL: https://pmoascode.com/principles/traceability/ 1Layer 1 · Principles · Explainer 03Traceability over dense documentation. Value lives in the links between thin, richly connected artifacts. ## The unit of value is the link. Dense documentation defeats its own purpose. A 40-page Word document describes a project in exhaustive detail, yet it cannot tell you why a status is red or which decision accepted the risk that caused it, so you read everything to find anything. Traceability replaces density with linkage. Each thin artifact (a charter, a RAID entry, a decision record) carries a stable ID and typed references to the others, so a reader can walk from any status to its root cause in five hops without opening a deck. ## The thread in practice. Does every requirement get tested? Every hop below is a typed link that CI checks on every pull request. Test CaseAUR-TC-001 wizard → account active, zero tickets tests → Acceptance CriterionAUR-AC-001 new customer set up, no support ticket verifies → Product RequirementAUR-PR-014 self-serve onboarding flow traces to → Business RequirementAUR-BR-001 onboarding under 2 days which serves → CharterAUR-charter objective: 14 days → under 2 ## The schema enforces this. Every requirement is an item with a stable ID and typed links, so the lineage is a queryable graph that CI checks. Ask "which requirements have no test?" and the tool answers. documents/PRJ-001-AUR/prd.md ## Product Requirements - **AUR-PR-014** (traces: AUR-BR-001): the product shall provide a self-serve onboarding flow. ## Acceptance Criteria - **AUR-AC-001** (verifies: AUR-PR-014): a new customer completes setup with no support ticket created. ← previous Automation & audit next → Derived status src/pages/principles/traceability.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Derived status URL: https://pmoascode.com/principles/derived-status/ 1Layer 1 · Principles · Explainer 04Derived status over self-reported status. Nobody types a color. Status is computed from the documents and their check results, the same way a build result is computed from the code. ## Who picks the color. Self-reported RAG asks the person with the most at stake to grade their own work, under an incentive to stay green. The grade drifts toward calm long before the project does. Derived status removes the question. The checks look at the document set and pick the color from what they find: Audit results An approved document that no longer passes its audit pulls the project off green. Coverage Requirements with no verifying test are a named, counted cause. Risk against appetite Open risks amber the project only at or above a declared severity threshold, so writing risks down is never punished. Freshness An operations catalog past its review date ambers itself. Nobody has to notice. ## Every color has causes. An amber page lists the findings that made it amber, each one pointing back to a document. A green page states what was verified rather than presenting silence as health. When the reader asks why, the answer is on the page, and fixing the cause is the only way to change the color. This is running in public. The portfolio that governs PMO as Code and the Refuge for Humans project derive their dashboards this way, including when the answer is amber. ## People can lower the color. They can never raise it. Human judgment still counts, in one direction. A project lead who sees trouble the checks can't see yet flags it in a status report, and the derivation honors the flag as one of its causes. The asymmetry is the point A written report can pull a green project to amber. Nothing a person types can turn a failing derivation green. The pressure to soften a color for a stakeholder meeting has nowhere to land. ← previous Traceability next → Composable definitions src/pages/principles/derived-status.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Composable definitions URL: https://pmoascode.com/principles/composable/ 1Layer 1 · Principles · Explainer 05Composable definitions over one-off, siloed tools. Every document kind shares one grammar, so a tool written once works on all of them, and a capability added once applies everywhere. ## One grammar, twenty-one kinds. A charter, a risk register, and a test-case document look different to a reader, and identical to the machine: frontmatter, required sections, typed items, link clauses. The validator, the consistency checker, the traceability matrix, and the dashboards each get written once against that shape. Adding a kind starts with data, a trio of files, and the shared machinery applies to it from day one: validation, audit, links, the matrix. When the operations kind shipped, only its genuinely new behavior needed engine work (a review date that ambers the project when it lapses); everything the other twenty kinds already had came free. a kind is three files schema/operations.schema.json # what the frontmatter must declare criteria/operations.criteria.yaml # what the audit checks templates/operations.template.md # what an author starts from ## Profiles compose kinds into expectations. A profile is a named bundle: which kinds a project of this type is expected to carry. Lean-startup expects a lighter set than regulated-industry, and operations expects a service catalog with a review date. Because profiles are definitions rather than tooling, adopting one, forking one, or publishing your own is an edit, and the same audit enforces whichever set you name. The four shipped profiles → ## Composition at the boundaries. The definitions compose outward as well. The standard is a versioned specification with a conformance suite, so an implementation other than docassert can exist and prove itself against the same cases. The execution bridge maps each project to a delivery repo through its anchor document, so one portfolio can fan out across many codebases. Checks stack in two tiers, a deterministic gate that blocks and an AI advisory layer that flags, and either runs without the other. One-off tools at the edges Teams will always write private glue, and that is fine. The line this principle draws: glue may consume the documents, and it may not become the place where a definition lives that the shared tooling can't see. ← previous Derived status next → The as-code family src/pages/principles/composable.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # The as-code family URL: https://pmoascode.com/as-code/ The as-code family The as-code family. PMO as Code did not invent its pattern. It applies a discipline that infrastructure, documentation, process, and policy each adopted first, one practice at a time, over the last two decades. ## The shared pattern. Every member of the family makes the same move: take a practice that lived in hand-work and tribal knowledge, and express it as plain-text files in version control. Four things follow from that one move. One source of truth The files are authoritative. Anything derived from them is a build output, and anything that contradicts them is drift. Review before change Changes arrive as diffs, get reviewed as diffs, and merge with a named author and a timestamp. Validation by machine Automation checks every change against the rules before it lands, so the standard is enforced rather than encouraged. History for free Who changed what, when, and why stops being a records-management project. It is the commit log. ## The family. Infrastructure as Code → The ancestor. Servers stopped being hand-built and became declared state that tooling converges toward. It proved the whole posture. Documents as Code → Technical writers moved documentation into Git and CI. Business documents raise the stakes: they carry commitments, so validation has to reach into structure. Process as Code → A process written in a wiki describes; a process written as automation executes. The gap between the two is where procedures rot. Policy as Code → Rules that machines evaluate against every change. Branch protection is the version most teams already run without naming it. Governance as Code → The system around the rules: decision rights, recorded approvals, oversight loops, and exceptions with a trail. Compliance as Code → Controls checked by machines, evidence accumulating as a by-product, audits that read the record instead of reconstructing it. GitOps deserves a mention alongside these: the practice of keeping a system converged with its declared sources through automated reconciliation loops. PMO as Code leans on it directly, since the delivery boards are reconciled against the documents the same way a cluster is reconciled against its manifests. ## Where PMO as Code sits. PMO as Code is the family pattern applied to project and portfolio management. The documents are the declared state, the audit is the validation, the merge is the recorded decision, and status is derived rather than reported. Each member of the family contributed a proven piece, and the contribution pages that follow name exactly which piece came from where. Start with the ancestor → The five defaults → ← previous Composable definitions next → Infrastructure as Code src/content/pages/as-code.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Infrastructure as Code URL: https://pmoascode.com/as-code/infrastructure/ The as-code family Infrastructure as Code. The ancestor. Before it, every server was a snowflake: hand-configured, undocumented, and impossible to rebuild with confidence. After it, infrastructure became declared state that tooling converges toward. ## Where it came from. CFEngine started automating server configuration in 1993. Puppet and Chef carried the idea through the 2000s, and once cloud providers exposed everything behind an API, Terraform generalized it in 2014: entire environments, from networks to DNS, declared in text files and applied by a tool. Kief Morris gave the practice its book in 2016, by which point it had stopped being a technique and become the default. The operational change mattered more than the tools. Infrastructure changes started arriving as pull requests. A reviewer could see exactly what would change before it changed, and the applied environment could be checked against the declaration afterward. ## What it proved. Declared state beats remembered state A file that says what should exist outlives every engineer who knew what did exist. Convergence beats correction Tooling that continuously pulls reality toward the declaration fixes drift without anyone noticing it first. Reproducibility is a property, not a project If the environment is declared, rebuilding it is running the tool again. Review works for operations The pull request turned out to be a better change-approval board than the change-approval board. ## What PMO as Code borrows. The posture, wholesale. The document set declares the portfolio the way Terraform files declare an environment. Dashboards and matrices are the applied state, rebuilt from the declaration on every change. Reconciliation loops keep the delivery boards converged with the documents, and staleness checks flag drift the moment a derived artifact falls behind its source. The one-line inheritance "Nobody SSHes into production to fix it by hand" becomes "nobody edits a status deck to fix the story by hand." ← previous The as-code family next → Documents as Code src/content/pages/as-code-infrastructure.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Documents as Code URL: https://pmoascode.com/as-code/documents/ The as-code family Documents as Code. Technical writers made this move a decade ago: documentation as plain text in version control, built and checked by the same CI as the product. Business documents are the harder, more valuable version of the same idea. ## The docs-as-code movement. Through the 2010s, documentation teams walked away from binary formats and CMS silos. Docs became Markdown next to the code, changes became pull requests, CI caught broken links and style violations, and the published site became a build output. Anne Gentle’s Docs Like Code put a name on the practice in 2016, and large documentation platforms run this way today. The movement proved that writing survives contact with engineering tooling, and that writers benefit from it: reviewable changes, real history, and a publish pipeline nobody operates by hand. ## Business documents raise the stakes. A tutorial that goes stale wastes a reader’s afternoon. A business document that goes stale misleads a decision: charters carry objectives and spending authority, requirements carry commitments to build, risk registers carry known dangers and their owners, and approvals carry accountability. That is why checking business documents means more than linting prose. Whether a sentence is well-formed matters less than whether the requirement it states traces to a business reason, is verified by a test, and still passes the criteria it was approved against. ## What structural validation takes. The reference approach gives every document kind a machine-checkable shape, so a validator can treat a charter the way a test suite treats a module. Frontmatter schema Identity, kind, project, status, and dates are declared fields with a schema, so a document missing its basics fails before anyone reads it. Required sections Each kind names the sections it must contain. An empty risk register is a finding, and a charter with no scope section can't reach approved. Typed items Requirements, risks, and tests are identified items with a grammar, so they can be counted, linked, and covered. Link clauses Traces between items are typed and checked. A broken trace blocks the merge the way a broken import blocks a build. Judgment stays prose. The objective’s wording, the mitigation’s reasoning, and the lessons in a review are written by people; the grammar covers identity and claims so the machine can hold them steady. The document model → All twenty-one kinds → ← previous Infrastructure as Code next → Process as Code src/content/pages/as-code-documents.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Process as Code URL: https://pmoascode.com/as-code/process/ The as-code family Process as Code. A process written in a wiki describes; a process written as automation executes. Between the two sits every procedure that was documented once and drifted quietly ever since. ## The wiki gap: described processes drift. Most organizations document their processes and then operate from memory. The documented version and the operated version diverge, nobody notices because nothing checks, and the divergence surfaces during an incident or an audit. Software delivery closed this gap by making the pipeline the process. Nobody consults a wiki page to remember how to release; the release process is a workflow, and running it is following it. The process cannot drift from its documentation because the automation is the documentation. ## The PMO’s processes can run. The recurring procedures of portfolio governance turn out to be automatable in exactly the same way. Each of these operates today in the reference deployments: Document review Every changed document is validated on the pull request, and the whole traceability graph is checked before merge. Scope intake When approved scope merges in the governance repo, the delivery boards are scaffolded within seconds, routed per project. Progress roll-up When the last story under a feature closes, the feature closes itself, with the record on the issue. Drift repair Reconciliation runs keep boards converged with documents, and a sentinel sweeps for stalled automation and opens findings on itself. ## What should stay written. Judgment-heavy procedures do not belong in a workflow file: how to run a steering conversation, when to escalate, what to do in a situation nobody predicted. The honest test is drift: if the written procedure and reality can diverge silently, encode the procedure; if a person must weigh the situation each time, write it down and govern the writing. The halfway house Procedures that need human hands can still live under the gate: a runbook as a governed document, with numbered steps, changed only by pull request. The steps stay human; the change control is code. ← previous Documents as Code next → Policy as Code src/content/pages/as-code-process.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Policy as Code URL: https://pmoascode.com/as-code/policy/ The as-code family Policy as Code. A rule that runs is a rule that holds. Policy as code takes rules out of the binder and evaluates them by machine against every change, before the change lands. ## A rule that runs. Infrastructure teams got here first, again: tools like Open Policy Agent and HashiCorp Sentinel evaluate declared rules against every proposed change, so “storage must be encrypted” stops being an intention in a standards document and becomes a check that fails the deployment. The property that matters is binding-ness. A written policy depends on everyone remembering it under deadline pressure. An executed policy is simply in the way of any change that violates it, uniformly, including changes made by its authors. ## The everyday version: branch protection. Branch protection is policy as code without the branding, and most engineering teams already run it: these checks must pass, this many reviewers must approve, this branch cannot be pushed to directly. The rules are configuration, they are evaluated on every merge, and the enforcement leaves a record. Every repository in the PMO as Code fleet runs under it, including the one that publishes this page. ## Policy in the PMO. Governance criteria become binding the same way: The quality bar A document that fails validation, or breaks a requirements trace, cannot merge. The standard is enforced by the repository, whoever the author is. Required signatures Where regulation demands a named human approval, a required reviewer models it, and the sign-off lands in the merge record. Scope discipline Delivery work traces to approved scope, and a guard flags work that arrives without it. Recorded exceptions Real policy needs an escape hatch that leaves a trail: an exception label a human applies deliberately, visible in the history, never applied by automation. How gates become policy → The enforcement wiring → ← previous Process as Code next → Governance as Code src/content/pages/as-code-policy.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Governance as Code URL: https://pmoascode.com/as-code/governance/ The as-code family Governance as Code. Policy is the rules. Governance is the system around them: who decides, how decisions are recorded, how oversight happens, and what becomes of exceptions. That system can be encoded too. ## Beyond the rules: who decides, and where it’s recorded. Platform teams reached this layer after policy as code proved itself. A single rule that blocks an unencrypted bucket is policy; the account-vending machinery, the org-wide guardrails, the review boards replaced by codified escalation paths, all of that is governance expressed as configuration rather than as a committee’s habits. The practical difference shows up in questions. Policy answers “is this change allowed?” Governance answers “who was allowed to decide that, where is the decision recorded, and who is watching the watchers?” ## The operating model, encoded. A PMO is mostly governance, which is why this member of the family maps so directly. Each element of the operating model has an encoded form running in the reference deployments: Decision rights Who may approve what is branch protection configuration: required reviewers on the paths they own. The org chart stops being an argument. The record of decisions A merged pull request is the minutes: who approved, when, exactly what changed, and which version of the criteria it was judged against. Lifecycle enforcement A document moves draft to proposed to approved, and the checks tighten as it does. Approval is refused mechanically when criteria are not measurable, whoever asks. Oversight loops Staleness gates, drift detectors, and a sentinel that opens findings on the automation itself, so the oversight layer is itself overseen. Exceptions complete the model. A governed exception carries a label a person applied deliberately, visible in history, never applied by automation, so deviating from the rule is possible and remembering the deviation is guaranteed. ## What stays human. The decisions. Code carries the record, the enforcement, and the escalation path; it does not decide whether the business case is sound or the risk is worth accepting. Governance as code removes the clerical layer between a decision-maker and a trustworthy record, and leaves the judgment where it belongs. Policy as Code → Watch it govern this project → ← previous Policy as Code next → Compliance as Code src/content/pages/as-code-governance.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Compliance as Code URL: https://pmoascode.com/as-code/compliance/ The as-code family Compliance as Code. Compliance is proving to someone outside that your controls hold. The as-code version checks the controls by machine and lets the evidence accumulate as a by-product of working, instead of being excavated once a year. ## The practice: controls as executable tests. Infrastructure teams turned compliance baselines into executable tests: Chef’s InSpec expressed entire compliance profiles as code that runs against real systems, and OpenSCAP did the same for hardening standards. A control stopped being a sentence in a binder and became a check with a pass or a fail and a timestamp. The consequence that matters is continuity. When controls run on every change, compliance is a property the system has all year, and the audit becomes a read of the record rather than a reconstruction of it. ## Evidence as a by-product. The questions an auditor asks a PMO have machine-collected answers here, and each answer is generated by the ordinary act of working: Who approved this, under what? A merged pull request with a named reviewer, timestamped, showing the exact document version and the criteria it passed. Nobody hunts for the email thread. Does every requirement have a test? The traceability matrix regenerates on every change, so coverage is provable on demand rather than asserted from memory. Were the checks actually run? Every gate run is retained in the Actions history with its verdict, on the exact commit it judged. Where a signature is legally required? A required reviewer models it, and the sign-off lands in the merge record. The regulated-industry profile expects the heavier document set from the start. ## What it does not claim. Passing your own checks is not certification. Compliance as code makes evidence cheap, current, and complete; the bar itself is still set by the framework and judged by the auditor. PMO as Code ships the mechanics, and it makes no certification claims on your behalf or its own. Where human gates still belong → The regulated-industry profile → ← previous Governance as Code next → Artifact Crosswalk src/content/pages/as-code-compliance.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Artifact Crosswalk URL: https://pmoascode.com/crosswalk/ 2Layer 2 · Reference ApproachThe artifact crosswalk: traditional artifacts and their as-code equivalents. Each row pairs an artifact the traditional PMO maintains with the as-code form that replaces it. Open any row to see the YAML definition and the artifact it generates. The output panels illustrate the tool's output format. Traditional PMOPMO as CodeStatus deck→Audit result, posted on every PR YAML definition --- kind: charter project: PRJ-001-AUR id: AUR-charter --- ## Objective Onboarding 14d → under 2d Generated output ✓ all checks passed frontmatter · sections · criteriaclear to mergeRAID log in Excel→Risk register in Git, checked on PR YAML definition kind: risk-register ## Risks - **AUR-RISK-001** (threatens: AUR-BR-001): … Probability: High. Impact: High. Owner: alex.kim. Response: dual-run. Generated output ✓ risk-items-complete merged by pull request, reviewer on recordthreatens AUR-BR-001Charter in Word→charter.md validated on every change YAML definition --- kind: charter sponsor: jordan.lee --- ## Success Criteria - p50 onboarding below 48h Generated output ✓ schema valid · 6 sections measurable criteria ✓approved by merged pull requestSteering approval email→A merged PR with a named reviewer YAML definition # branch protection required_status_checks: contexts: - audit - consistency Generated output ✓ merged · reviewer on record audit ✓ · consistency ✓Manual RAG status→Deterministic checks with reasons YAML definition ## Success Criteria - Onboarding p50 below 48 hours. - Support tickets fall by at least 80%. - CSAT rises above 4.5 / 5. Generated output ✓ measurable-success-criteria (3/3) Pass or fail comes from the checks,with the reason attached.Requirements that drift across docs→One generated traceability matrix YAML definition **AUR-BR-001**: reduce onboarding time **AUR-PR-014** (traces: AUR-BR-001): self-serve flow **AUR-AC-001** (verifies: AUR-PR-014): … **AUR-TC-001** (tests: AUR-AC-001): … Generated output Requirements Traceability Matrix AUR-BR-001 → AUR-PR-014 → AUR-AC-001 → AUR-TC-001 generated from the linksStage-gate checklist→A required check in CI YAML definition on: [pull_request] jobs: audit: docassert validate consistency: docassert consistency Generated output CI · audit ✓ · consistency ✓ merge blocked until greenon every pull request ← previous Compliance as Code next → Core Concepts src/pages/crosswalk.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Core Concepts URL: https://pmoascode.com/concepts/ 2Layer 2 · Reference ApproachCore Concepts. Everything is a Markdown document with YAML frontmatter and defined sections. Requirements are authored as linked items, which is what makes the whole set testable and traceable. ## One shape for every document. Every kind shares one shape: frontmatter (typed metadata a JSON Schema checks) and required sections (the audit checks they're present and complete). Plain Markdown a person can read and a diff can review. Examples use Aurora, the fictional sample project; its people are invented. documents/PRJ-001-AUR/charter.md ---kind: charterproject: PRJ-001-AURid: AUR-chartersponsor: jordan.leestatus: approved---## ObjectiveCut median onboarding time from 14 days to under 2 days.## Success Criteria- Median onboarding time drops below 48 hours. - Manual setup tickets fall by at least 80%. ## Every document belongs to a project. Documents are organized project-first, and each project has a self-identifying id such as PRJ-001-AUR, which pairs a unique sequence with a short code. A project.md anchors each folder. documents/PRJ-001-AUR/ project.md # id: PRJ-001-AUR · code: AUR · sponsorcharter.md # id: AUR-charterbrd.md # items: AUR-BR-001, AUR-BR-002prd.md # items: AUR-PR-014 (traces: AUR-BR-001)… The AUR- code namespaces every id, so AUR-BR-001 and ATL-BR-001 are different requirements in different projects, each globally unique and each declaring its own project. A generated projects.yaml registers them all. ## Requirements are linked items. The unit of traceability is the item: a bullet with a stable ID and typed links to what it depends on. That turns a pile of documents into a queryable graph. the chain, across four documents **AUR-BR-001**: The business shall reduce onboarding time to under 2 days.**AUR-PR-014** (traces: AUR-BR-001): The product shall provide a self-serve flow.**AUR-AC-001** (verifies: AUR-PR-014): Given a new customer…, then an active account exists.**AUR-TC-001** (tests: AUR-AC-001): Complete the wizard → account active, zero tickets. BR → PR → FR/NFR → AC → TC. Every hop is a typed link the pipeline checks: broken references block, and the matrix is generated from them. ## Two tiers of checks. The same split runs on every document and across the whole graph. Structural: deterministic and blocking Required fields and sections present, success criteria measurable, risks have owners, references resolve. Plain code, reliable enough to gate a merge. Integrity errors block at any status; completeness gaps are advisory for drafts and gate once a document is proposed. Open risks move the derived status only when they score at or above a configurable appetite. The CLI itself is covered by a published stability policy, and the policy's command reference is regenerated from the parser so it cannot drift. Semantic: AI-graded and advisory Is the objective specific? Does AUR-PR-014 actually fulfil AUR-BR-001? Each link is scored via the Anthropic API against a rubric chosen for its relation, since a mechanism contributing to a KPI deserves a different judgment than a story implementing a requirement. Grades are cached by content hash, so unchanged links are never re-billed and the per-run budget goes to new work. Results post to the PR. They never block. ## Twenty-one kinds, one pattern. Each kind is a template + schema + criteria trio. Adding a kind means adding a trio, with no new code for the common cases. project The project anchor, with unique id, code, sponsor, and status. charter Objective, measurable success criteria, sponsor, budget. business-case Problem, options, recommendation, costs, benefits. brd Business requirements as BR items. prd Product requirements (PR) + acceptance criteria (AC). frnfr Functional (FR) & non-functional (NFR) requirements. user-story Stories (US) in "As a… I want…" form. test-cases Test cases (TC) that verify acceptance criteria. adr Architecture decisions with a recorded status. risk-register Risks with probability, impact, owner, response. raci-stakeholder Roles matrix with one Accountable per activity. qa-test-plan Scope, environments, measurable exit criteria. data-migration-plan Sources, field mapping, validation, cutover. release-cutover-plan Ordered cutover steps and a rollback trigger. rollback-plan Trigger conditions and ordered rollback steps. hypercare-plan Support window, severities, measurable exit. runbook Operational procedures, monitoring, escalation. operations Service catalog with levels, measures, review freshness. status-report Period, RAG, cites risks from the register. post-implementation-review Outcomes vs objectives, lessons, actions. benefits-realization Measurable benefits vs the business case. ← previous Artifact Crosswalk next → Quickstart src/pages/concepts.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Quickstart URL: https://pmoascode.com/quickstart/ 2Layer 2 · Reference ApproachQuickstart: empty repo to a validated, merged document. This walkthrough uses docassert, the reference implementation. Everything is Git, Markdown, and GitHub Actions, with no other tools. Time to complete: ~20 minutes. Requires: git, Python 3.10+, a terminal, and a GitHub repo. Prefer to let Claude do it? See Quickstart with Claude Code → Starting a fresh repo? The template pre-wires steps 1–2 and 8. Step 1 ## Get docassert. Install it from PyPI. It validates documents, checks cross-document consistency, generates the traceability matrix, and derives per-project status. terminal pipx install docassert # or: pip install docassertdocassert --version# AI advisory extra: pipx install "docassert[ai]" Step 2 ## Anchor a project. Everything is organized by project. A project.md anchor gives it a unique id (PRJ-001-AUR), a code that namespaces every document and item, and, optionally, a profile that declares the documents it should carry. documents/PRJ-001-AUR/project.md ---kind: projectid: PRJ-001-AUR # PRJ--, unique across all projectscode: AUR # namespaces ids: AUR-charter, AUR-BR-001name: Aurora — Customer Onboarding Overhaulsponsor: jordan.leestatus: active # proposed | active | on-hold | closedprofile: regulated-industry # optional: the expected document set---## Overview## Scope terminal docassert new project --code AUR --name "Aurora — Customer Onboarding Overhaul"# docassert: created documents/PRJ-001-AUR/project.md # id auto-numbereddocassert projects --out projects.yaml # generate the registry from the anchors# docassert: wrote projects.yaml (1 project) Tip Keep a brand-new project proposed while you fill it in, so its profile gaps stay advisory, and flip it to active when you want missing required documents to block. Step 3 ## Author a document. Scaffold a document into the project folder with docassert new, which fills in the identity and suggests the next free item ids, then write the content. Below is a completed charter, and the guides cover converting an existing Word document. terminal docassert new charter --project PRJ-001-AUR# docassert: created documents/PRJ-001-AUR/charter.md documents/PRJ-001-AUR/charter.md ---kind: charterproject: PRJ-001-AURid: AUR-chartertitle: Aurora — Customer Onboarding Overhaulsponsor: jordan.leebudget: { amount: 1200000, currency: USD }dates: { created: 2026-01-15, target: 2026-12-15 }status: approved---## ObjectiveCut median onboarding time from 14 days to under 2 days by replacing manual setup with a self-serve flow.## Success Criteria- Median onboarding time (p50) drops below 48 hours. - Onboarding CSAT rises above 4.5 / 5. - Manual setup tickets fall by at least 80%.# … Scope, Milestones, Risks, Approval … Step 4 ## Unit-test it. Structural checks are deterministic and block a merge; AI checks (with a key) advise. The output below is abridged from a real run. terminal docassert validate documents/PRJ-001-AUR/charter.md documents/PRJ-001-AUR/charter.md ✓ frontmatter-schema: valid against the schema ✓ required-sections: all 6 present and non-empty ✓ measurable-success-criteria: all 3 state a measurable threshold ✓ risks-have-owner-and-mitigation: all risks name an owner + mitigation ✓ dates-consistent: created 2026-01-15 → target 2026-12-15 ✓ unique-id: id 'AUR-charter' is unique○ objective-is-specific: advisory (needs ANTHROPIC_API_KEY)✓ All structural checks passed — clear to merge. Why it fails when it should A vague "make customers happier" success criterion has no measurable threshold, so measurable-success-criteria blocks and cites the exact criterion that failed. Completeness checks like this stay advisory while a document is a draft and begin to gate once it is proposed, so work in progress is never punished. Step 5 ## Check consistency across documents. This is where the model pays off. Requirements trace end to end, the registry stays fresh, and each profiled project carries its required documents. Broken links block; the AI judges whether each child fulfils its parent. terminal docassert consistency consistency (cross-document) ✓ item-id-uniqueness: all 24 item IDs are unique ✓ referential-integrity: all references resolve ✓ required-links: all required upstream links present ✓ coverage: all approved items are covered ✓ profile-completeness: 3 project(s) with advisory gaps (not enforced yet)# AI advisory, e.g.:● AUR-PR-015 —traces→ AUR-BR-002 score 0.40"progress emails don't obviously reduce support tickets" Step 6 ## Generate the traceability matrix. The matrix is derived from the links on every change, so it is always current and nobody maintains it. terminal docassert rtm --project PRJ-001-AUR# Requirements Traceability Matrix — AUR | Business Req | Product Req | Func/NFR | Acceptance | Test | |--------------|-------------|-----------|------------|------------| | AUR-BR-001 | AUR-PR-014 | AUR-FR-101| AUR-AC-001 | AUR-TC-001 | | AUR-BR-002 | AUR-PR-015 | AUR-NFR-05| AUR-AC-002 | AUR-TC-002 | Step 7 ## Derive status and see what's missing. Status is derived, never typed. Scope it to one project, roll up the portfolio, or build the whole site. Because Aurora is on a profile, its page also shows which required documents are complete, incomplete, or missing. terminal docassert status --project PRJ-001-AUR # one project's RAG + document setdocassert status --index # the portfolio tabledocassert pages --out _site # index.html + a page per project# Projects — AMBER | Project | Code | RAG | Docs | Required | Open risks | |------------------------|------|-------|------|----------|------------| | Aurora — Onboarding | AUR | AMBER | 20 | 9/9 | 2 | | Atlas — Partner Portal | ATL | AMBER | 5 | 0/4 | 0 | The document set Aurora is 9/9 required complete. A project still filling in shows each required kind as complete / incomplete / missing, and a missing required document turns the page red and blocks the merge once the project is active. Step 8 ## Gate it in CI and make it binding. Two jobs run on every pull request, but GitHub only blocks a merge when branch protection requires them. That setting is what turns advisory checks into a real gate. .github/workflows/audit.yml on: [pull_request]jobs:audit: # validate each changed documentsteps: - { uses: actions/checkout@v4, with: { fetch-depth: 0 } } - uses: c4g-john/docassert-action@v1with: { command: validate, changed-only: 'true' }consistency: # the graph + registry + profile completenesssteps: - { uses: actions/checkout@v4 } - uses: c4g-john/docassert-action@v1with: { command: consistency } terminal # make both checks required before a PR can mergegh api -X PUT repos/OWNER/REPO/branches/main/protection --input - <<'JSON' { "required_status_checks": { "strict": true, "contexts": ["audit", "consistency"] } } JSON One-time repo setup · Branch protection: require audit and consistency on main (above). Without it, the checks run but never block.· GitHub Pages: Settings → Pages → Source: GitHub Actions, so status-pages.yml can publish the live dashboard. It is one-time and manual.· AI advisory (optional): add ANTHROPIC_API_KEY as an Actions secret. Structural checks gate without it; this just adds the AI scoring. The template path, exercised for real On 2026-07-05 a fresh copy of the template was taken from repo creation to a merged, gate-checked pull request and a live dashboard in about seven minutes, using only the README. The run also surfaced a real bug (a fresh project scaffold failed its own validation), which shipped as a fix in docassert 1.0.2 the same day. The evidence is public: the repo, the gated pull request, and the live dashboard. What's next Let Claude Code scaffold the whole thing from one prompt, convert an existing Word document, or explore the document kinds in the reference. Use the template →Quickstart with Claude Code →The guides →The document kinds → ← previous Core Concepts next → Quickstart with Claude Code src/pages/quickstart.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Quickstart with Claude Code URL: https://pmoascode.com/quickstart-claude/ 2Layer 2 · Reference ApproachQuickstart with Claude Code. Skip the manual steps. Copy one prompt, paste it into Claude Code, and it scaffolds the pipeline, converts your documents, and wires the gate, asking you for the specifics as it goes. Prefer to do it by hand? See the manual quickstart → ## The prompt. set up the whole pipelinepaste into Claude Code Set up "PMO as Code" in this repository using docassert (pip install docassert · https://github.com/c4g-john/docassert). 1. Add docassert and its GitHub Actions workflows: validate + consistency on every pull request plus the status-pages dashboard, using c4g-john/docassert-action@v1 (copy the workflows from github.com/c4g-john/pmo-as-code-template). 2. Create a project anchor at documents/PRJ-001-/project.md with a unique id, a short CODE, a sponsor, and a profile (start with lean-startup). 3. Turn my existing project docs into PMO-as-Code documents using the standard templates: charter, business requirements, product requirements, test cases. Flag anything the source doesn't cover as a TODO; never invent facts. 4. Run docassert validate and docassert consistency, and fix whatever blocks. 5. Show me docassert status --project PRJ-001-, then tell me exactly what to click to turn on branch protection and GitHub Pages. Start by asking me for the project name, sponsor, and any existing documents. Copy prompt and open Claude Code ↗Copy only The button copies the prompt and opens claude.ai/code, where you paste and send. Or run claude in your terminal and paste. ## What you'll need. Claude Code The terminal claude CLI, the desktop app, or the web app at claude.ai/code. Install from claude.com/claude-code. A GitHub repo New or existing. Claude adds the pipeline and workflows in a branch and opens a pull request, so nothing lands on main until you approve it. ## What Claude will do. It follows the same path as the manual quickstart, drives it for you, and stops to ask whenever a decision is yours. 01 Add docassert + the CI workflows the tool, plus audit / consistency / status-pages 02 Anchor your project project.md with a unique id, code, and a profile 03 Convert your documents into the standard templates, with gaps marked as TODOs 04 Validate and check consistency and fix whatever blocks a merge 05 Derive the status page RAG, coverage, and the required-document set 06 Explain the repo setup branch protection and Pages, the one-time manual settings ## More prompts. Smaller, targeted asks once you're set up. convert one Word documentpaste into Claude Code Convert this Word document into a PMO-as-Code charter using docassert (pip install docassert · github.com/c4g-john/docassert). Extract the text, map it to the charter template, and flag anything the source is missing as a TODO rather than inventing it. Then run docassert validate and show me what fails. Copy prompt add a project to an existing setuppaste into Claude Code We already use docassert. Add a new project: create documents/PRJ-00N-/project.md (pick the next free number and a short CODE), set a profile, regenerate projects.yaml, and scaffold its charter. Then run docassert consistency and docassert status --project for the new project. Copy prompt What's next See the steps Claude runs in the manual quickstart, or browse the document kinds and guides. The manual quickstart →The document kinds → ← previous Quickstart next → Guides src/pages/quickstart-claude.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Guides URL: https://pmoascode.com/guides/ 2Layer 2 · Reference ApproachGuides. Task-focused walkthroughs that stand alone, so start wherever the need is. Convert a Word document Bring an existing document in with the doc-to-pmo skill, which marks gaps as TODOs.↓ Author linked requirements Write BR → PR → AC → TC as items, and let consistency check the chain.↓ Gate documents in CI Run the audit and consistency jobs on every PR; make the gate binding.↓ Add a new document kind A template, a schema, and a criteria file, usually with no code at all.↓ Start a new project Give a project a unique ID, a folder, and its own derived status page.↓ Bridge to GitHub Projects Turn approved stories into Features, sub-issue Stories, and a governed board.↓ Guide 01 ## Convert a Word document. Bring an existing charter, business case, or BRD into the pipeline without retyping it. ### Extract the source text terminal pip install "docassert[convert]" docassert extract path/to/charter.docx # .docx / .pdf / .md / .txt → plain text ### Let the skill map it The doc-to-pmo skill fills the standard template from the source and marks anything the source didn't supply as a TODO. documents/PRJ-001-AUR/charter.md (first pass) ## Success Criteria- TODO: source says "faster onboarding" — add a measurable target.## Risks- Migration may slip. (TODO: assign an Owner and a Mitigation.) Faithful over passing An incomplete source produces a document that fails the audit and lists the exact gaps to fill, which is the outcome a faithful conversion should produce. Guide 02 ## Author linked requirements. Write each requirement as an item with a stable ID and a typed link to what it refines. across four documents in documents/PRJ-001-AUR/ # brd.md- **AUR-BR-001**: The business shall reduce onboarding time to under 2 days.# prd.md- **AUR-PR-014** (traces: AUR-BR-001): The product shall provide a self-serve flow. - **AUR-AC-001** (verifies: AUR-PR-014): Given a new customer…, then an active account exists.# test-cases.md- **AUR-TC-001** (tests: AUR-AC-001): Complete the wizard → account active, zero tickets. terminal docassert consistency ✓ referential-integrity: all references resolve ✓ coverage: all approved items are covered# broken links block; the AI advises on whether each link truly holds Guide 03 ## Gate documents in CI. Two jobs run on every pull request; branch protection makes them binding. .github/workflows/audit.yml on: [pull_request]jobs:audit: # validate each changed documentsteps: - { uses: actions/checkout@v4, with: { fetch-depth: 0 } } - uses: c4g-john/docassert-action@v1with: { command: validate, changed-only: 'true' }consistency: # check the whole traceability graphsteps: - { uses: actions/checkout@v4 } - uses: c4g-john/docassert-action@v1with: { command: consistency } terminal # require both checks before a PR can mergegh api -X PUT repos/OWNER/REPO/branches/main/protection --input - <<'JSON' { "required_status_checks": { "strict": true, "contexts": ["audit", "consistency"] } } JSON Guide 04 ## Add a new document kind. A kind is a trio: a template, a JSON Schema for its frontmatter, and a criteria file listing the checks. Most kinds need no new code. criteria/decision-log.criteria.yaml kind: decision-logrequired_sections: [Overview, Decisions]item_sections: - { section: Decisions, prefix: DEC }checks: - { id: frontmatter-schema, blocking: true } - { id: required-sections, blocking: true } - { id: items-well-formed, blocking: true } Config-driven checks Some checks are reusable via config: measurable_sections makes bullets in a section require a threshold; steps_sections requires an ordered list. New kinds reuse them with zero code. Guide 05 ## Start a new project. Give a project a unique identity, a folder, and its own always-current status page. Pick the next sequence number and a short code, and drop a project.md anchor in its folder. ### Anchor the project documents/PRJ-002-ATL/project.md ---kind: projectid: PRJ-002-ATLcode: ATLname: Atlas — Partner Portal Modernizationsponsor: mia.chenstatus: proposed---## Overview## Scope ### Register it and see its page Every document you add under documents/PRJ-002-ATL/ uses the ATL- code, so its items (ATL-BR-001) never collide with any other project's. terminal docassert projects --out projects.yaml # regenerate the registrydocassert status --project PRJ-002-ATL # this project's derived RAGdocassert pages --out _site # adds PRJ-002-ATL.html to the portfolio Unique by construction A CI check fails if projects.yaml drifts from the anchors or two projects claim the same id or code, keeping identity unambiguous as the portfolio grows. Guide 06 ## Bridge to GitHub Projects. Once user stories are approved, the bridge runs delivery from them. Each product requirement becomes a Feature issue, each story becomes a sub-issue of its Feature, and a scope guard flags any issue that lacks a matching item in the documents. A deliberate exception gets the scope:exempt label, applied only by a person and never by the automation, so the exception is as auditable as the rule. Scope flows from documents to GitHub, and execution state flows back only into the dashboards. terminal docassert bridge scaffold --repo OWNER/REPO # Features + Story sub-issues, idempotentdocassert bridge reconcile --repo OWNER/REPO # police the board; non-zero exit on driftdocassert bridge status --repo OWNER/REPO # delivery figures per feature The template ships three dormant workflows for this. Set the repository variable BRIDGE_ENABLED to true and they scaffold on document merges, reconcile on issue activity, and close a Feature when its last story lands. Everything runs on the built-in token. Boards need one extra token Mirroring items onto a Projects v2 board requires a classic personal access token with only the project scope, stored as the PROJECTS_TOKEN secret. Fine-grained tokens cannot reach personal-account boards. Then docassert bridge create-board and the scaffold's --project-number flag do the rest, filling Type, Doc, and PMO Project fields on every item. The documents stay in charge An issue typed straight onto the board gets a scope:unverified label and an alert within seconds, and the Delivery panel on the status page reads from the board without ever changing the document-derived RAG. One documents repo, many code repos Add repo: OWNER/NAME to a project's anchor and the bridge routes that project's Features and Stories to its own code repository; --project scopes any bridge command to one project. Projects sharing a repository reconcile as a union, racing scaffolds converge on one issue per marker, and an explicit --repo still applies the whole plan to one repository. ← previous Quickstart with Claude Code next → Reference src/pages/guides.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Reference URL: https://pmoascode.com/reference/ 2Layer 2 · Reference ApproachReference. Every kind is a Markdown document with YAML frontmatter and required sections. The canonical schema and audit criteria ship inside the docassert package, and your repo can override them; this page is the map. All document kinds share kind, id, project, title, and status. The remaining fields vary by kind and are listed below. ## The shared shape. Frontmatter is typed metadata (validated against a JSON Schema); sections carry the content (checked for presence and completeness). any-document.md ---kind: project: PRJ-001-AUR # the owning project's idid: AUR-brd # -, globally uniquetitle: Human-readable titlestatus: draft # draft | proposed | approved | baselined---## A Required SectionContent, plus traceable items where the kind defines them. ## Project identity. Documents live in per-project folders. Each project is anchored by a project.md (the 21st kind, project) whose id is the canonical PRJ-NNN-CODE. The CODE namespaces every document id (AUR-brd) and item id (AUR-BR-001). documents/PRJ-001-AUR/project.md ---kind: projectid: PRJ-001-AUR # PRJ--, unique across all projectscode: AUR # 2–6 letters; namespaces this project's idsname: Aurora — Customer Onboarding Overhaulsponsor: jordan.leestatus: active # proposed | active | on-hold | closed--- An optional repo: OWNER/NAME on the anchor maps the project to its code repository for the execution bridge. docassert projects generates projects.yaml from these anchors, and a CI check fails if it drifts or an id/code is duplicated. Checks: project-id-format. ## Item & link syntax. Traceable rows are bullets with a bold ID and optional typed links. Broken links always block; coverage of approved items is enforced. convention - **AUR-PR-014** (traces: AUR-BR-001, AUR-BR-003): The product shall provide a self-serve flow. relationmeaningexample traceschild requirement → the parent it refinesPR→BR · FR/NFR→PR · US→PR verifiesacceptance criterion → the requirement it checksAC→PR/FR teststest case → the acceptance criterion it exercisesTC→AC threatensrisk → the item it endangersRISK→BR/PR affectsdecision → the requirement it changesADR→FR/NFR ## The twenty-one document kinds. projectcharterbusiness-casebrdprdfrnfruser-storytest-casesadrrisk-registerraci-stakeholderqa-test-plandata-migration-planrelease-cutover-planrollback-planhypercare-planrunbookoperationsstatus-reportpost-implementation-reviewbenefits-realization projectThe identity anchor: one per project folder, declaring the canonical id (PRJ-NNN-CODE), code, sponsor, lifecycle status, delivery profile, and the repo its execution bridges to. frontmatterkind, id, project, title, status, code, name, sponsor, profile, repo sectionsOverview · Scope checksproject-id-format charterThe contract for a piece of work. frontmatterkind, id, project, title, status, sponsor, budget, dates sectionsObjective · Success Criteria · Scope · Milestones (dated bullets draw the timeline; the target date is an implicit milestone) · Risks · Approval checksmilestones-dated · measurable-success-criteria · risks-have-owner-and-mitigation · dates-consistent business-caseThe justification, upstream of the BRD. frontmatterkind, id, project, title, status, sponsor sectionsProblem Statement · Options Considered · Recommendation · Costs · Benefits checksrequired-sections brdBusiness requirements. frontmatterkind, id, project, title, status, owner sectionsPurpose · Business Requirements · Out of Scope itemsBR checksitems-well-formed prdProduct requirements and acceptance criteria. frontmatterkind, id, project, title, status, owner sectionsOverview · Product Requirements · Acceptance Criteria itemsPR (traces BR, optionally after another PR for sequencing) · AC (verifies PR) checksitems-well-formed frnfrFunctional & non-functional requirements. frontmatterkind, id, project, title, status, owner sectionsOverview · Functional Requirements · Non-Functional Requirements itemsFR · NFR (trace PR) checksitems-well-formed user-storyUser stories. frontmatterkind, id, project, title, status, owner sectionsOverview · User Stories itemsUS (traces PR) checksstory-format test-casesTest cases. frontmatterkind, id, project, title, status, owner sectionsOverview · Test Cases itemsTC (tests AC) checksitems-well-formed adrArchitecture decision log. frontmatterkind, id, project, title, status, owner sectionsOverview · Decisions itemsADR (affects FR/NFR) checksadr-items-have-status risk-registerThe risk register. Risks carry a disposition (open, mitigated, accepted, closed); open risks hold derived status at amber only at or above the configurable risk appetite (probability × impact ≥ 6 by default), so writing a risk down does not cost the project its green. frontmatterkind, id, project, title, status, owner sectionsOverview · Risks itemsRISK (threatens BR/PR) checksrisk-items-complete · risk-disposition-valid raci-stakeholderRoles and responsibilities. frontmatterkind, id, project, title, status, owner sectionsStakeholders · RACI Matrix checksraci-one-accountable qa-test-planTest strategy and gates. frontmatterkind, id, project, title, status, owner sectionsScope · Test Approach · Environments · Entry Criteria · Exit Criteria checksmeasurable-exit-criteria data-migration-planHow data moves and is verified. frontmatterkind, id, project, title, status, owner sectionsScope · Source Systems · Field Mapping · Validation · Cutover · Rollback checksmapping-table release-cutover-planThe go-live switch. frontmatterkind, id, project, title, status, owner sectionsOverview · Pre-Cutover Checklist · Cutover Steps · Verification · Rollback Trigger checksnumbered-steps (Cutover Steps) rollback-planThe abort path. frontmatterkind, id, project, title, status, owner sectionsOverview · Trigger Conditions · Rollback Steps · Verification checksnumbered-steps (Rollback Steps) hypercare-planHeightened post-go-live support. frontmatterkind, id, project, title, status, owner sectionsOverview · Support Window · Severity Levels · Escalation · Exit Criteria checksmeasurable-exit-criteria runbookOperational procedures. frontmatterkind, id, project, title, status, owner sectionsOverview · Prerequisites · Procedures · Monitoring · Escalation checksnumbered-steps (Procedures) operationsA governed service catalog for ongoing work, chartered per period. frontmatterkind, id, project, title, status, owner, review_by sectionsOverview · Services itemsSVC checkssvc-items-complete · ops-review-fresh (advisory; a stale review turns derived status amber) status-reportA point-in-time status. frontmatterkind, id, project, title, status, owner, period, rag sectionsSummary · Progress · Risks & Issues · Next Steps checksreferences-risk post-implementation-reviewClosure and lessons. frontmatterkind, id, project, title, status, owner sectionsSummary · Outcomes vs Objectives · What Went Well · What Could Improve · Lessons Learned · Follow-up Actions checksrequired-sections benefits-realizationBenefits vs the business case. frontmatterkind, id, project, title, status, owner sectionsOverview · Benefits · Measurement · Realized Value checksmeasurable-items (Benefits) The full JSON Schema, audit criteria, and a runnable sample for every kind live in the pipeline repo. Fork them; add your own.schema/ · criteria/ · templates/ → ← previous Guides next → The standard src/pages/reference.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # The standard URL: https://pmoascode.com/standard/ 2 Layer 2 · Reference Approach The standard: a versioned, testable specification. PMO as Code is specified, versioned, and testable, so that implementing it never requires reading the reference implementation's source code. The current version is v0.8.1, still marked draft while it hardens toward a 1.0 of its own. ## What it specifies. The document model Frontmatter fields, required sections, and document lifecycle for every kind, from charter to benefits realization. Identity and item grammars Project identifiers, document identifiers, and the item grammar that makes requirements, risks, and tests countable and linkable. Typed link relations What traces may point at, what sequencing means, and which broken links block a merge. Two-tier check semantics The normative line between deterministic structural checks, which block, and semantic AI checks, which only advise. Profiles How named document-set expectations are declared, composed, and enforced. Derived status The inputs a conforming implementation must derive RAG from, including risk appetite and the rule that reports lower colors and never raise them. ## Versioning. The specification is versioned independently of any implementation. A breaking change to a grammar or to blocking semantics requires a major version bump, and changes land the way everything else in this ecosystem lands: a pull request against SPEC.md, gated and recorded. Hardening the standard to 1.0 is itself a chartered project in the public portfolio, with its own derived status: PRJ-003-STD, live. ## The conformance suite. The spec ships with 73 executable conformance cases across five categories (document, grammar, graph, profiles, registry), each pairing an input with the verdict a conforming implementation must produce. The reference implementation pins a spec version and verifies itself against that version’s suite; docassert 1.x currently pins v0.8.1. Why the suite matters "Implements PMO as Code" is a checkable claim, made against numbered cases, rather than a marketing sentence. An alternative implementation earns the same claim the same way. ## Implementing it. Read SPEC.md, run your implementation against the conformance suite, and use the artifacts mirror for the canonical templates. The spec is Apache 2.0; a conforming implementation owes nobody anything. The specification repo → The 21 kinds in detail → ← previous Reference next → Integrations src/content/pages/standard.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Integrations URL: https://pmoascode.com/integrations/ 2 Layer 2 · Reference Approach Integrations: GitHub-native by design. There are no connectors to build or maintain. The whole pipeline runs on Git, GitHub Actions, and, for the advisory layer only, the Anthropic API, so there is nothing else to wire up or break. Claude maps any source document into the standard templates, and from there it is version control the whole way down. ## GitHub Actions. Two jobs run on every pull request: audit validates each changed document, and consistency checks the whole traceability graph. Both post their results as a PR comment. .github/workflows/audit.yml on: [pull_request] jobs: audit: # validate each changed document steps: - { uses: actions/checkout@v4, with: { fetch-depth: 0 } } - uses: c4g-john/docassert-action@v1 with: { command: validate, changed-only: 'true' } consistency: # check the whole traceability graph steps: - { uses: actions/checkout@v4 } - uses: c4g-john/docassert-action@v1 with: { command: consistency } ## Branch protection. Require both checks on main, and a document that fails validation or breaks a requirements trace can no longer merge. terminal # require both checks before a PR can merge gh api -X PUT repos/OWNER/REPO/branches/main/protection \ --input - <<'JSON' { "required_status_checks": { "strict": true, "contexts": ["audit", "consistency"] } } JSON ## The Anthropic API. The one external service, used only by the advisory layer. The AI reads a document or a traceability link and scores it, and one repo secret switches it on. It fails safe: with no key, the advisory checks skip and the deterministic gate is unaffected. terminal # enable AI advisory scoring (optional) gh secret set ANTHROPIC_API_KEY --repo OWNER/REPO # without it, advisory checks report: ○ objective-is-specific: skipped — no ANTHROPIC_API_KEY (advisory only) ## The skills & templates library. The real “integration” is Claude itself. The doc-to-pmo skill takes a Word doc, a PDF, or pasted text and maps it into the standard Markdown templates, marking anything the source didn’t supply as a TODO. Ships with the tool The templates, the audit criteria, and the conversion skill all ship inside the docassert package. docassert init scaffolds them into your repo and places the skill in .claude/skills/, where Claude Code discovers it. Any source goes in, and standard, testable documents come out. Browse the library → ← previous The standard next → Profiles src/content/pages/integrations.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Profiles URL: https://pmoascode.com/profiles/ 3Layer 3 · ProfilesProfiles: named document-set expectations. A profile is a named bundle of expectations for a project: which document kinds it must carry, which are merely recommended, and how strict the gate is. Point a project at one, and its status page tells you what's still missing. Profiles are to this standard what distributions are to a kernel: the principles hold still while implementations diverge. ## What a profile is. A small YAML file that lists the kinds a project is expected to carry, at two levels, required and recommended. A project opts in with one line of frontmatter. profiles/regulated-industry.yaml name: regulated-industryenforce_when: active # gaps block CI only once the project is activeexpects:required: [charter, business-case, brd, prd, frnfr, test-cases, risk-register, raci-stakeholder, qa-test-plan]recommended: [adr, runbook, status-report, benefits-realization] documents/PRJ-001-AUR/project.md kind: projectid: PRJ-001-AURstatus: activeprofile: regulated-industry # opt in Complete · incomplete · missing The project page classifies each expected kind: complete (present, approved, passing), incomplete (present but still draft), or missing. A missing required kind blocks the merge once the project reaches its enforce_when stage. Before that, a proposed project shows the same gaps as advisory amber. ## The profiles that ship. Four profiles live in the reference library today. Point a project at one, or copy it as a starting point. regulated-industry The full governance spine for finance, healthcare, or government. requiredcharter, business-case, brd, prd, frnfr, test-cases, risk-register, raci-stakeholder, qa-test-plan recommendedadr, runbook, status-report, benefits-realization lean-startup The minimum spine. Gaps stay advisory until the project goes active, so a small team is never blocked for unfinished docs. requiredcharter, brd, prd, test-cases recommendedrisk-register agile-delivery Story-led: every story traces to a product requirement, every acceptance criterion to a test. requiredcharter, prd, user-story, test-cases recommendedbrd, risk-register operations Period-chartered keep-the-lights-on: a governed service catalog with a review date that turns derived status amber by itself when it lapses. requiredoperations recommendedrisk-register, runbook ## Author your own. Drop a new file in profiles/ and point projects at it. For deeper changes, such as extra required sections or stricter checks, edit the criteria/ trio the kinds share. profiles/our-org.yaml name: our-orgenforce_when: activeexpects:required: [charter, brd, prd, test-cases, risk-register]recommended: [adr, runbook] Then profile: our-org in each project's project.md. A CI check flags an unknown profile, so a typo can't slip through. ← previous Integrations next → Adoption & Maturity src/pages/profiles.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Adoption & Maturity URL: https://pmoascode.com/adoption/ 3 Layer 3 · Profiles Adoption & maturity model. A staged path from your first validated document to a fully traceable set, where each stage delivers value on its own. Crawl takes an afternoon, walk adds the gate on every pull request, and run turns on cross-document consistency across the whole set. ## Stage 1 · Crawl: one document, validated. Pick one document. Author documents/PRJ-001-AUR/charter.md, covering the frontmatter and the required sections. Run docassert validate locally, and you have a versioned, schema-checked document in a place with history. What you get A versioned document, structural validation you can run in one command, and a Git history of every change, which retires the question of which version of the charter is current. What you skip CI, cross-document consistency, and the AI layer, all optional at this stage, while you build the habit of truth-in-Git before automating on top of it. Checklist: charter.md ✓ · docassert validate ✓ ## Stage 2 · Walk: gated on every pull request. Put docassert validate in a GitHub Actions workflow and turn on branch protection. Add a few more kinds, such as a BRD and a PRD, and a document that misses the standard can no longer merge, with the reasons posted on the PR. What you get A binding gate, an audit result on every pull request, and more document kinds under the same standard. The PMO begins to operate the way an engineering team does. Typical timeline About a day to wire the Action and require the check on main. Most of the effort is agreeing the criteria with stakeholders. Checklist: audit.yml ✓ · branch protection ✓ · 3+ kinds ✓ ## Stage 3 · Run: the full set, with consistency enforced. Every document kind in Git, with the cross-document consistency job enforcing traceability, the AI advisory layer on, and the RTM generated on every change. Requirements trace end to end, broken links block the merge, and the matrix regenerates on every change. What you get Every requirement traces to a test, broken links block, the AI flags weak links for review, and the traceability matrix stays current without anyone maintaining it. The run claim At run, you can answer "which requirements have no test?" in seconds from the graph, without calling anyone or reading a deck. Checklist: consistency required ✓ · AI advisory on ✓ · RTM generated ✓ ← previous Profiles next → vs Traditional PPM src/content/pages/adoption.md|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # vs Traditional PPM URL: https://pmoascode.com/vs/ ComparePMO as Code vs traditional PPM. We make strong claims and show our work, including the rows where traditional approaches still hold. PPM = Project & Portfolio Management (tools like MS Project, Planview, Clarity, Smartsheet). Traditional PPMPMO as Code Status deck (weekly, manual)→Audit result, posted on every PR RAG self-reported by the PM→Deterministic checks decide pass/fail Approval email chain→A required check + a merged PR Charter in Word, v47_FINAL.docx→charter.md, versioned, schema-validated RAID log in Excel, shared drive→Risk register in Git, reviewed by PR Requirements drifting across 6 docs→One traceability graph, checked in CI "Who approved this?" means an email search→git log + the merged PR reviewer PM headcount for the reporting layer→One docassert run per pull request Human signature required (regulatory)≈A required reviewer, recorded in Git Tool-trained PMs, high switching cost→Any compliant tool, vendor-neutral standard PMO as Code wins Context-dependent ## Where as-code wins clearly. It wins wherever stale data costs more than learning YAML, which in practice means portfolios beyond about five projects, organisations where audit and traceability matter, and teams already working in Git. Engineering-led orgs Git is already the source of truth for code. Extending it to the portfolio is a small step for a team that already lives there. Regulated industries An audit trail in Git records who changed what, when, and who approved it, and it satisfies most audit requirements better than email threads can. ## Where traditional gates still belong. Some decisions require a named individual's sign-off: a legal filing, a board resolution, a contractual milestone payment. PMO as Code accommodates them by requiring a named reviewer on the pull request, recorded in the Git history. That is a stronger record than an approval email nobody can find later. Our position Gates move from the default to the documented exception. When a signature is genuinely required, it becomes a required reviewer inside the audit trail instead of an email chain outside it. ← previous Adoption & Maturity next → FAQ src/pages/vs.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # FAQ URL: https://pmoascode.com/faq/ CompareFAQ. The questions every audience asks first. Is this just another PPM tool?+ No. PMO as Code is a vendor-neutral standard: business documents as Markdown with defined schemas and audit criteria, validated in Git. docassert is a reference implementation that shows it working end to end, but any tool that implements the specification conforms. There is no product to buy.What about regulators who require a human signature?+ A merged pull request with a named reviewer is the signature, timestamped in Git history and enforceable through branch protection. Where a specific person's sign-off is legally required, make that reviewer required in branch protection or add a signed-off field for the audit to check. The record is far more auditable than an approval email no one can find.Do we have to move everything to Git at once?+ No. Start with one document, validate it locally, add the GitHub Actions gate when you are ready, and turn on cross-document consistency last. Each crawl-walk-run stage delivers value on its own, and nothing forces a big-bang migration.Can the AI block a merge?+ No, by design. The deterministic structural checks (required fields, measurable success criteria, resolving requirement links) are what block a merge, because they are reliable. The AI checks are advisory. They score a document or a traceability link and post the reasoning to the pull request without ever gating it, and they fail safe, skipping when no key is set.What if my organisation doesn't use Git?+ The whole model assumes version control, and in practice almost every organisation already has Git somewhere, so start there. If version control is genuinely absent, that conversation happens upstream of this framework, because a single versioned source of truth is the entire premise.How is this different from a spreadsheet with strict conventions?+ Three things a spreadsheet cannot do: schema validation (so the conventions actually hold), a queryable traceability graph across documents (so you can see that every requirement traces to a test), and a merge gate that blocks non-conforming changes before they land. A spreadsheet with conventions still relies on a human to keep it honest.What is docassert, exactly?+ docassert is the reference implementation: a small Python CLI and GitHub Action that validates each document against its criteria, checks cross-document consistency, and generates the traceability matrix. It exists to prove the standard works end to end, and the specification defines what any other implementation must do.Who owns the standard?+ The principles (Layer 1) are meant to be owned by no one. The reference approach (Layer 2), meaning the specification, templates, criteria, and docassert, is maintained by John Tanner at C4G Enterprises as a public, Apache-licensed library you can fork. Profiles (Layer 3) are open to anyone. ← previous vs Traditional PPM next → News src/pages/faq.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # News URL: https://pmoascode.com/news/ NewsNews: what shipped, when. One entry per release or milestone, dated, with the artifacts linked so every claim can be checked. Subscribe via RSS. 2026-07-05 The first-hour test caught a bug; the fix is docassert 1.0.2 A fresh template copy reached a green gate and a live dashboard in about seven minutes, README only, and surfaced a real scaffold bug on its first command. 2026-07-05 C4G Enterprises releases PMO as Code, an open standard that makes project status a build artifact The launch press release: reference implementation docassert reaches stable 1.0, and the standard runs its own development in public, where every claim can be checked. 2026-07-05 pmoascode.com rebuilt as a fully static site The site is now a static Astro build: zero client JavaScript by default, llms.txt and the sitemap generated from the same records that render the pages. 2026-07-04 docassert 1.0: the stability promise is now binding The reference implementation reaches 1.0 on PyPI. STABILITY.md becomes a binding SemVer contract covering the CLI surface, JSON shapes, and exit codes. 2026-07-03 The PMO as Code portfolio goes public The portfolio that governs PMO as Code is now run as PMO as Code, in public: five projects, gated documents, and a live derived dashboard. ← previous FAQ next → Press & share kit src/pages/news/index.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub → --- # Press & share kit URL: https://pmoascode.com/press/ SharePress & share kit. Facts you can verify, copy you can quote, boilerplate you can paste, and images of the real product. The chips below are claims; each one links to the artifact that backs it. docassert 1.0 · stableSemVer-boundApache-2.0spec v0.873 conformance cases21 document kindslive dashboard ## The ten-second version. “Project status is a build artifact.” That is the whole idea. For status to be built rather than reported, the documents underneath it have to be structured, tested, and gated. The tool that does the testing is docassert: “unit testing for business documents.” Boilerplate · 50 words PMO as Code makes project status a build artifact. Charters, BRDs, and risk registers live in Git as structured Markdown. Changes are tested and cannot merge until they pass, and the passing documents compile into red, amber, or green. There is no field where anyone types a status. Boilerplate · 100 words PMO as Code is an open standard for running a project management office from version-controlled files. Business documents (charters, BRDs, PRDs, risk registers) are structured Markdown with schemas and audit criteria, validated on every pull request by docassert, the Apache-licensed reference implementation. Requirements carry stable ids and typed links, which turns “which requirements have no test?” into a query. Project status is compiled from the documents and published as a live dashboard with no edit button. The project runs its own portfolio this way, gates and all, in public repositories, so every claim it makes about itself can be checked. ## Assets. Free to use when covering the project. The dashboard screenshots are captures of live pages, taken with whatever states the portfolio actually had that day. Download everything (zip, ~0.5 MB) ↓ Portfolio dashboard PNG · 2880×1800 · live capture↓ file Project dashboard PNG · 2880×1800 · live capture↓ file Social card PNG · 1200×630↓ file Logomark SVG · scales to any size↓ file Demo animation SVG · animates in-place↓ file # PMO as Code — fact sheet- One-liner: project status is a build artifact- Tool: docassert, stable 1.x, Apache-2.0- Spec: v0.8 · 73 conformance cases- Contact: press@c4genterprises.com … Fact sheet Markdown · plain text↓ file ## Three story angles. 01Infrastructure-as-Code, pointed at the PMO DevOps solved “the wiki is stale and the spreadsheet lies” for infrastructure a decade ago. Declare truth in files, validate every change, derive state instead of reporting it. PMO as Code points that playbook at project governance, with the same Git and the same gates.The principles → 02It governs itself, and you can check The portfolio that builds PMO as Code is run as PMO as Code: five projects, every scope change through a gated pull request, a public dashboard rebuilt from the governing documents on every merge. A skeptical reader can audit any claim from their couch.The live portfolio dashboard → 03Dashboards that can’t lie There is no text box for status. Coverage comes from the traceability graph, risk from a scored register with a declared appetite, delivery from real issue states, and an amber page has to say why it is amber. A real project converted from a Word BRD shows the whole loop running.The case-study dashboard → ## Press boilerplate. Third-person paragraphs for the foot of an article, usable verbatim without approval. The launch press release is on the news feed. Media contact: press@c4genterprises.com. Release-tied announcements run on the news feed (RSS). About PMO as Code PMO as Code is an open, vendor-neutral standard for running a project management office from version-controlled files. Business documents live in Git as structured Markdown, every change is tested and gated before it merges, and project status is compiled from the documents rather than reported by hand. The standard, its specification, and its reference implementation are Apache-2.0 and free to adopt at pmoascode.com. About docassert docassert is the reference implementation of PMO as Code: a command-line tool that validates business documents the way a test suite validates code. It reached a stability-guaranteed 1.0 in July 2026, is installable from PyPI, and ships the schemas, audit criteria, templates, and delivery profiles of the standard. Details at docassert.com. About the author PMO as Code was created by John Tanner, founder of C4G Enterprises Inc. His career spans kicking off a DevOps movement at the White House Communications Agency, development-practice consulting for Fortune 500 companies worldwide, delivery modernization at Freddie Mac, and leading the PMO at a Fortune 200 company. He publishes the standard and its tooling as open source. ## Share copy. A neutral blurb anyone may share as their own. The numbers in it are real. SHORT · X / MASTODON / BLUESKY Your project charter should fail CI.PMO as Code: business documents as version-controlled Markdown, unit-tested on every PR, status compiled instead of typed. The tool (docassert) just hit stable 1.0. Apache-2.0.pmoascode.com ## Fact sheet. What it isA vendor-neutral standard for running a PMO from version-controlled files. Business documents are structured Markdown, validated like code on every change. Requirements trace end to end, and project status is compiled from the documents. The tooldocassert · Python 3.10–3.14 · pipx install docassert · brew install c4g-john/tap/docassert The scopeTwenty-one document kinds. Two tiers of checks: deterministic structural checks gate the merge, and AI-graded semantic checks only advise. An execution bridge turns approved stories into GitHub issues, and the dashboards are compiled from the documents. The caveatThe tool is stable at 1.0. The specification is v0.8 and still a draft; its conformance rules may tighten before a spec 1.0. WhoJohn Tanner, C4G Enterprises Inc. · linkedin.com/in/tannerjs · why he wrote this Press contactpress@c4genterprises.com Names“PMO as Code” is the standard. The tool is lowercase “docassert”, tagline “unit testing for business documents”. ← previous News src/pages/press.astro|Updated 2026-07-05|written and maintained by John Tanner · C4G Enterprises|News|Press & share kitEdit on GitHub →