Getting Started

Add GxP.MD compliance to your project in four steps.

1

Create a GxP.MD file

Create a file named GxP.MD at your project root. This is the compliance contract your AI agent reads.

GxP.MD 
---
gxpmd_version: "2.1.0"

project:
  name: "My Project"
  version: "0.1.0"

regulatory:
  profile: pharma-standard
  frameworks: ["21 CFR Part 11"]

risk:
  overall: MEDIUM

annotations:
  schema_version: "1.0"
  required_tags:
    source: ["@gxp-req", "@gxp-spec", "@gxp-risk"]
    test: ["@gxp-spec", "@trace", "@test-type", "@gxp-risk"]

artifacts:
  engine: rosie
  directory: .gxp
  formal_artifacts: optional

gates:
  pre_commit:
    - annotations_valid
    - no_untagged_gxp_code
  pre_merge:
    - all_tests_pass
    - coverage_meets_threshold

harden:
  frequency: per_sprint

agent:
  mode: risk_proportionate
---

# Core Principles

Annotations are the source of truth.
Traceability lives in code, not separate docs.

Download the full starter template from the Templates page for all available configuration options.

2

Choose a regulatory profile

Set the regulatory.profile field to match your industry and regulatory requirements.

Profile Use When Key Standards
pharma-standard Pharma manufacturing, distribution, quality systems 21 CFR Part 11, EU Annex 11, GAMP 5
medical-device Medical device software, IVDs IEC 62304, ISO 13485, 21 CFR 820
clinical-trial Clinical trial data systems, eCRF, CTMS ICH E6(R2), GDPR, 21 CFR Part 11
laboratory LIMS, testing and calibration systems 21 CFR Part 58, ISO 17025

See the Profiles page for a detailed comparison of what each profile requires.

3

Start developing with annotations

GxP.MD v2 is annotation-first. Add compliance metadata directly to your code as structured comments. Your agent will guide you through the annotation format.

src/auth/login.ts 
/**
 * @gxp-req REQ-001 "User authentication"
 * @gxp-spec SPEC-001-001 "OAuth2 PKCE flow"
 * @gxp-risk HIGH
 */
export async function authenticateUser(credentials: LoginCredentials) {
  // implementation
}
tests/oq/auth/login.test.ts 
/**
 * @gxp-spec SPEC-001-001
 * @trace US-001-001
 * @test-type OQ
 * @gxp-risk HIGH
 */
describe("User authentication", () => {
  it("should authenticate valid credentials", () => {
    // test implementation
  });
});

Annotations are lightweight during development. Formal artifact files in .gxp/ are optional — only needed for complex HIGH risk components.

4

Run harden mode per sprint

At the end of each sprint (or release), run harden mode to formalize the compliance record. This generates:

  • Traceability Matrix — Complete REQ → US → SPEC → CODE → TEST chains from annotations
  • Compliance Status Report — Metrics, gap analysis, and sign-off section
  • Evidence Packages — Formalized test results with manifests and optional signatures
  • Gap Analysis — Missing annotations, incomplete chains, coverage shortfalls

The last harden output IS your audit record. There is no separate audit preparation phase. This satisfies ALCOA+ Contemporaneous compliance.

Next Steps