Templates

---
gxpmd_version: "2.1.0"

project:
  name: "YOUR_PROJECT_NAME"
  id: "YOUR_PROJECT_ID"
  version: "0.1.0"
  owner: "YOUR_NAME <your.email@YOUR_ORG.com>"
  contact: "quality@YOUR_ORG.com"

regulatory:
  profile: pharma-standard       # pharma-standard | medical-device | clinical-trial | laboratory
  jurisdictions: [FDA, EMA]
  frameworks:
    - "21 CFR Part 11"
    - "EU Annex 11"
  gamp_category: 5               # 1=Infrastructure, 3=COTS, 4=Configured, 5=Custom

risk:
  overall: HIGH                   # HIGH | MEDIUM | LOW
  matrix:
    HIGH:
      coverage_threshold: 95
      required_tiers: [IQ, OQ, PQ]
      signing_required: false
      review_required: true
    MEDIUM:
      coverage_threshold: 80
      required_tiers: [OQ, PQ]
      signing_required: false
      review_required: false
    LOW:
      coverage_threshold: 60
      required_tiers: [OQ]
      signing_required: false
      review_required: false

annotations:
  schema_version: "1.0"
  required_tags:
    source: ["@gxp-req", "@gxp-spec", "@gxp-risk"]
    test: ["@gxp-spec", "@trace", "@test-type", "@gxp-risk"]
  format: block_comment           # block_comment | decorator | companion_file

artifacts:
  directory: .gxp
  engine: none                    # rosie | custom | none
  formal_artifacts: optional      # required | optional | none
  traceability_enforcement: strict  # strict | warn | off

gates:
  pre_commit: [annotations_valid, no_untagged_gxp_code]
  pre_merge: [all_tests_pass, coverage_meets_threshold, review_complete_if_required, no_orphan_annotations]
  per_release: [harden_sweep_complete, traceability_matrix_current, evidence_packages_complete]

harden:
  frequency: per_sprint           # per_sprint | per_release | manual
  outputs: [traceability_matrix, compliance_status_report, evidence_packages, gap_analysis]

agent:
  mode: risk_proportionate        # strict | risk_proportionate | advisory
---

# GxP.MD -- Compliance Instructions for AI Coding Agents (v2)

**This file is the compliance contract for this project.** An AI agent
reading only this file has everything it needs to operate compliantly.
Traceability lives in code annotations. Compliance is enforced at gates.

---

## 1. Session Start Protocol

When you begin a session on this project:

1. **Read this file.** Parse the YAML frontmatter for risk matrix,
   annotation requirements, and gate definitions.
2. **Read \`.gxp/system_context.md\`** if it exists, to understand
   system boundaries and intended use.
3. **Determine the risk level** of the area being modified by checking
   existing \`@gxp-risk\` annotations in the relevant source files.

## 2. Annotation Schema

Annotations are the source of truth for traceability. They live in code,
move with code, and are reviewed with code.

Example (TypeScript):
\`\`\`typescript
/**
 * @gxp-req REQ-001 "Authenticate users via secure credential exchange"
 * @gxp-spec SPEC-001-001 "OAuth2 PKCE flow implementation"
 * @gxp-risk HIGH
 */
export async function authenticateUser(creds: LoginCredentials) { }
\`\`\`

## [... Full template continues with Develop Mode, Harden Mode,
##  Risk-Level Behavior, Quality Gates, Evidence Capture, and more]
##
## Download the complete file below.

---
id: "00000000-0000-0000-0000-000000000000"   # Generate a UUID
project_name: "Your Project Name"
version: "0.1.0"
gxp_risk_rating: MEDIUM            # HIGH | MEDIUM | LOW
validation_status: DRAFT           # DRAFT | VALIDATED | DEPRECATED
intended_use: |
  Describe the system's intended use, target users,
  and regulatory context.
regulatory_context:
  primary_standards:
    - "21 CFR Part 11"
  gamp_category: 5
  data_classification: "GxP-Critical"
system_boundary:
  includes:
    - "src/"
    - "packages/"
  excludes:
    - "node_modules/"
    - "dist/"
---

# System Context

## Overview
[Describe the system, its purpose, and scope]

## Architecture
[High-level architecture description]

## Regulatory Scope
[Which regulations apply and why]

---
gxp_id: REQ-001                   # Sequential: REQ-001, REQ-002...
title: "Requirement Title"
parent_id: null                    # null for top-level requirements
description: |
  Detailed description of the requirement.
risk_level: MEDIUM                 # HIGH | MEDIUM | LOW
acceptance_criteria:
  - "Criterion 1"
  - "Criterion 2"
validation_status: DRAFT
---

# REQ-001: Requirement Title

## Description
[Detailed requirement description]

## Rationale
[Why this requirement exists]

## Risk Assessment
[Risk level justification]

---
gxp_id: US-001-001                # Format: US-{REQ}-{SEQ}
title: "User Story Title"
parent_id: REQ-001                # Links to parent requirement
acceptance_criteria:
  - "Given [context], when [action], then [result]"
  - "Given [context], when [action], then [result]"
verification_tier: OQ             # IQ | OQ | PQ
validation_status: DRAFT
---

# US-001-001: User Story Title

## As a [role]
I want [capability]
So that [benefit]

## Acceptance Criteria
1. Given [context], when [action], then [result]
2. Given [context], when [action], then [result]

---
gxp_id: SPEC-001-001              # Format: SPEC-{REQ}-{SEQ}
title: "Specification Title"
parent_id: US-001-001             # Links to parent user story
verification_tier: OQ             # IQ | OQ | PQ
design_approach: |
  Description of the implementation approach.
source_files:
  - "src/modules/feature/service.ts"
test_files:
  - "src/modules/feature/service.test.ts"
validation_status: DRAFT
---

# SPEC-001-001: Specification Title

## Design Approach
[How this will be implemented]

## Verification Method
[How compliance will be verified]

## Implementation Files
- `src/modules/feature/service.ts`

{
  "@context": "https://gxp.md/evidence/v1",
  "package_id": "OQ-SPEC-001-001-2026-02-07T120000Z",
  "spec_id": "SPEC-001-001",
  "tier": "OQ",
  "traced_user_story": "US-001-001",
  "system_state_hash": "",
  "git_commit": "",
  "created_at": "",
  "files": [
    {
      "path": "metadata.json",
      "hash": "",
      "size_bytes": 0
    },
    {
      "path": "environment.json",
      "hash": "",
      "size_bytes": 0
    },
    {
      "path": "test-output.log",
      "hash": "",
      "size_bytes": 0
    },
    {
      "path": "artifacts/test-results.json",
      "hash": "",
      "size_bytes": 0
    }
  ],
  "total_size_bytes": 0,
  "file_count": 4
}