Onboarding TRACE ALM onto a new project

This is the meta-playbook for adopting TRACE ALM on a new regulated software project. It does not duplicate the per-step playbooks; it lists them in order, plus the per-project decisions you have to make.

For the conceptual overview of what’s reusable vs. per-project, see Applying TRACE ALM to a new project.

Pre-flight checklist

• You have a private GitHub repo for the new product
• You have org-admin access on the GitHub org (needed to create the auto-stamp App)
• You have identified the qualified medical-device reviewer for the project (typically the same person as on BioFlow Pro, but per-project)
• You have a clean main branch on the new repo (or the willingness to start fresh)

Stage 1 — Bring the reusable folders across

From the BioFlow Pro repo, copy these folders to the new repo’s working tree:

tools/post_processor/
tools/auto_stamp/
tools/__init__.py
.claude/skills/strictdoc-requirements/
.github/workflows/pr_branch_tests.yml
.github/workflows/auto-stamp.yml
pyproject.toml      # or merge entries into the new repo's existing one
uv.lock
.gitignore          # check entries for Python tooling, StrictDoc output, test results, runs/
dart_test.yaml      # only if the new project is also Flutter/Dart

Adjust:

• pr_branch_tests.yml build steps to match the new project’s build chain (a non-Flutter project will need different Setup and Build steps)
• pyproject.toml to match the new project’s Python deps
• The auto-stamp script and post-processor are project-agnostic; do not modify them

Stage 2 — Author the project’s regulated artefacts

Create:

• regulatory-docs/10_system.sdoc — system / stakeholder requirements (SYS-), grammar header copied from BioFlow Pro’s
• regulatory-docs/11_srs.sdoc — software requirements (SRS-), grammar header copied from BioFlow Pro’s
• regulatory-docs/20_architecture.sdoc — software architecture (ARCH-), grammar header copied from BioFlow Pro’s
• regulatory-docs/30_unit_tests.sdoc, regulatory-docs/31_integration_tests.sdoc, regulatory-docs/32_system_tests.sdoc — same structure as BioFlow Pro
• regulatory-docs/strictdoc_config.py — same shape, project-specific title
• regulatory-docs/00_README.md — short intro
• changes/ directory + changes/README.md — copy from BioFlow Pro

Author the project’s first items in each tier + at least one test specification. Start with one SYS item (a stakeholder commitment), one SRS item (the software-level behaviour realising it), and one ARCH item (the architectural element behind that behaviour) — linked upward via derivedFrom. Keep the test specs minimal but real — you need at least one IT and one ST to validate the pipeline end-to-end.

Stage 3 — Configure CODEOWNERS

Create .github/CODEOWNERS listing the qualified reviewer for this project. See the CODEOWNERS playbook for the file structure and rationale per path.

If the project has a different qualified reviewer than BioFlow Pro, swap @DougYoungberg for that person’s GitHub handle.

Stage 4 — Create the project’s auto-stamp App

Follow the auto-stamp App playbook end-to-end, with these substitutions:

• App name: <project-slug>-autostamp (e.g. bioflow-autostamp for BioFlow, coronamed-autostamp for a hypothetical CoronaMed product)
• Repo to install on: the new project’s repo
• Branch-protection bypass list: that repo’s main branch
• Repo secrets: stored on the new repo

The reusable code in tools/auto_stamp/ and auto-stamp.yml reads the App’s identity from the secrets and from ${{ steps.app-token.outputs.app-slug }} — no per-project edits to those files are needed.

Stage 5 — Configure branch protection on main

Follow the branch-protection playbook. Same toggles, applied to the new repo’s main.

Stage 6 — Smoke-test the whole chain

Open a small test PR that touches regulatory-docs/11_srs.sdoc. Confirm:

1. The PR pipeline runs all four jobs and goes green
2. The qualified reviewer is auto-requested as code owner
3. The PR cannot merge until they approve
4. After merge, the auto-stamp Action runs and pushes REVIEWED_HASH + REVIEWED_BY to main
5. The next PR opens with the post-processor showing the requirement as reviewed

If all five steps work, TRACE ALM is operational on the new project.

Per-project things to update

File	Project-specific content
.github/CODEOWNERS	The qualified reviewer’s handle
.github/workflows/pr_branch_tests.yml	Build steps, installer build, smoke test for the project’s binary
visiontrace_tests/conftest.py	Project-specific test setup (e.g. license activation if applicable)
regulatory-docs/10_system.sdoc, regulatory-docs/11_srs.sdoc, regulatory-docs/20_architecture.sdoc, and regulatory-docs/*.sdoc	The project’s actual requirements (three-tier graph + test specs)
pyproject.toml	Project-specific Python deps if any
pubspec.yaml (or equivalent)	Build-system manifest

Everything else (tools/post_processor/, tools/auto_stamp/, the auto-stamp workflow, the skill file) is reusable as-is.

Documenting the new project’s setup

Once TRACE ALM is operational on the new project, the new project should:

1. Capture its specific App settings, CODEOWNERS, branch-protection toggles, and secrets in its own equivalents of these playbooks (or fork this trace-alm-docs/ site to document its own deployment)
2. Update its setup playbooks with last verified dates as the GitHub UI evolves
3. Cross-link to TRACE ALM’s central documentation site (this one) for the conceptual / shared content

This keeps each project’s documentation focused on its configuration while sharing the conceptual story.