v1
2Layer 2 · Reference Approach

Guides.

Task-focused walkthroughs that stand alone, so start wherever the need is.

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.