Applying TRACE ALM to a new project

TRACE ALM is intentionally factored so most of the system carries over to new regulated software products with minimal per-project effort. This page lists what’s shared, what’s per-project, and the order to set things up on a fresh repo.

For the full step-by-step, see the Onboarding TRACE ALM onto a new project playbook.

Reusable across projects (no edits needed)

These pieces are project-agnostic and can be lifted as-is onto a new repository:

• The post-processor at tools/post_processor/ — generic StrictDoc + test-results joiner; reads any regulatory-docs/ tree.
• The auto-stamp tooling at tools/auto_stamp/ — generic; reads CODEOWNERS + computes hashes for any .sdoc files.
• The CI pipeline structure in .github/workflows/pr_branch_tests.yml — the four-job pattern (dart-tests / build-and-package / system-and-rtm / smoke-and-perf). For a non-Flutter project the build steps differ, but the pattern of tests → build → system + RTM → smoke is reusable.
• The auto-stamp workflow at .github/workflows/auto-stamp.yml — generic; only references repo-specific values via ${{ secrets.* }} and ${{ github.* }}.
• The skill file at .claude/skills/strictdoc-requirements/SKILL.md — the authoring rules and review workflow definition. Project-agnostic; same rules apply.
• VisionTrace — installed as a pip package from the UIATest repo, parameterised per project via APP_EXE_PATH and a project-specific conftest fixture.

Per-project (must be set up fresh)

These pieces capture the project’s specific identity and have to be created or configured anew:

• regulatory-docs/ — the project’s requirements and test specifications. Empty for a new project; populate from the project’s specs.
• changes/ — the project’s change-record stream. Starts empty.
• .github/CODEOWNERS — names the qualified medical-device reviewer for this project’s regulated paths. The list of owned paths is generally the same; the owner’s GitHub handle is per-project.
• A new GitHub App — each project has its own auto-stamp App (e.g. bioflow-autostamp, <other-product>-autostamp). The App is installed only on its own repo and added to that repo’s branch-protection bypass list. See the auto-stamp App playbook for the exact creation steps.
• GitHub Actions secrets — AUTOSTAMP_APP_ID, AUTOSTAMP_APP_PRIVATE_KEY, plus any project-specific tokens (e.g. VISIONTRACE_TOKEN, ANTHROPIC_API_KEY, license keys).
• Branch-protection rules on main — same toggles, applied to the new repo. See the branch-protection playbook.
• The project-specific test conftest — e.g. visiontrace_tests/conftest.py carries BioFlow-specific knowledge (license-activation UI labels). Each new product needs its own equivalent.

Order of setup on a fresh repo

1. Bring the reusable folders across (tools/post_processor/, tools/auto_stamp/, .github/workflows/, .claude/skills/strictdoc-requirements/).
2. Create empty regulatory-docs/, changes/ and the StrictDoc grammar headers.
3. Fill .github/CODEOWNERS with the project’s qualified reviewer.
4. Register the new GitHub App on the org (see the App playbook). Install on this repo only.
5. Add the App to the branch-protection bypass list on main. Enable “Require review from Code Owners”.
6. Add the App’s ID and private key as repo secrets.
7. Author the project’s first SRS items and at least one test spec.
8. Open the first regulated PR. Confirm the pipeline runs end-to-end (CI green, code-owner approval requested, auto-stamp runs on merge, REVIEWED_HASH lands).

After step 8, TRACE ALM is operational on the new project.