Open-source toolkit for spec-driven development with pharma-grade rigor — built for AI agents to ship quality software using target-system specs as authoritative context. Compliance docs come free.
Inspired by ISPE GAMP 5 Second Edition (2022) V-Model + 21 CFR Part 11 + EU GMP Annex 11 (2025) + Annex 22 (AI/ML in pharma, 2025) + ICH Q9 (R1) + PIC/S PI 041-1. Designed for: pharma-IT consultancies developing software for regulated clients · indie hackers in regulated industries · R&D labs building internal tooling with AI assistance.
🚧 Status: feature-complete toolkit draft, pre-public-release. The template catalog, skill layer, Codex adapter parity, deterministic gates, worked example, and file-based work-item harness are in place. Current hardening focus: readiness diagnosis, run tracking, adapter compliance, catalog drift checks, and public-release polish.
New here? Open a Claude Code session in your project and run /gdd.start — the zero-state front door detects whether a .gxp-dev.yaml manifest exists, asks how you want to begin (build new / validate existing / hybrid / just learn), and — when the right lane isn't obvious — runs a short criticality lane advisor that recommends the regulated cascade (Lane A) or the agile dev harness (Lane B) with reasons, then routes you to the right skill. It recommends; you decide.
Start here: the full end-to-end walkthrough — both lanes, every command, where each deliverable lands, and the troubleshooting gates — is docs/user-manual.md. Prefer a picture? Open the self-contained visual guide docs/user-manual.html in a browser — the same content as flow diagrams.
- Getting started — clone and go
- Why this exists
- What it is, in one paragraph
- The radical idea
- Killer feature: the generative cascade
- What's inside the toolkit
- What this is NOT
- Audiences and use cases
- Positioning vs github/spec-kit
- Architecture in 5 minutes
- Requirement ID scheme
- V-Model coverage
- How a consumer project is structured
- The .gxp-dev.yaml manifest
- Status and roadmap
- Design principles
- Anti-goals
- Contributing
- Acknowledgments
- License
The repo is a template: your project lives in the clone, and the skills are pre-wired for your coding agent — no install step.
git clone https://github.com/aristo-Cat/gxp-driven-dev.git my-project # or "Use this template" on GitHub
cd my-project- Claude Code — open a session in the clone and run
/gdd.start. The/gdd.*commands are auto-discovered from the shipped.claude/skills/stubs (generated mirrors ofskills/). - Codex CLI — repo-level prompt discovery is pending upstream
(openai/codex#9848); until it lands, install once
with
cp .codex/prompts/*.md ~/.codex/prompts/, then run/gdd-start. The rootAGENTS.mdis picked up automatically. - Any other LLM/agent — point it at
skills/start/SKILL.mdand tell it to follow the procedure; the skills are plain Markdown, vendor-neutral by design.
/gdd.start routes you to /gdd.init, which writes the .gxp-dev.yaml manifest and — since your
project is the clone — offers to flip the root AGENTS.md from the toolkit-maintainer contract to
your consumer-project contract. From there the end-to-end guide is
docs/user-manual.md (visual version:
docs/user-manual.html).
Prefer the toolkit outside your repo? The standalone layout still works — see How a consumer project is structured.
AI coding agents (Claude Code, Cursor, Codex, GPT, Gemini) ship faster code than humans alone. But "vibe coding" — feeding the agent prose prompts and accepting whatever it returns — produces software that fails at audit (regulated domains) and fails at scale (enterprise tooling). The agent invents requirements, hallucinates package names, picks arbitrary architectures, loses coherence across sessions.
The fix is not less AI; the fix is better specs for the system being built or validated. Structured, versioned, traceable specifications used as the agent's authoritative context stop the agent from inventing and start it implementing what the target-system spec says.
This is a 40-year-solved problem in pharma. ISPE GAMP 5 has produced audit-grade specifications for computerized systems since the early 1990s — the most demanding software-spec discipline in industry, designed to survive FDA inspection. gxp-driven-dev borrows that rigor and adapts it for any team where spec quality matters: pharma-IT consultancies, R&D labs, indie founders in fintech / health-tech / aerospace / nuclear / automotive safety, enterprise teams that want their AI agents grounded.
As a side-effect, when the consumer project's target system happens to be in a regulated domain, the specs produced by this toolkit serve directly as compliance documentation. Zero extra effort.
A toolkit of AI-callable skills (Claude Code-first; ported to OpenAI Codex at full parity, plus a Cursor reference port) that potentiate AI agents with 33 canonical Markdown templates (URS, FS, DS, IQ, OQ, PQ, RA-INIT, RA-DET, CR, RTM, VR, PR, CC, IR, and 19 more) carrying declarative YAML frontmatter (typed placeholders, presets, validation rules, downstream consumers, instance frontmatter spec). Skills are generative: they draft cascade-down (URS → FS → RA → tests → code/evidence) for the target system described by the consumer project, using approved upstream specs as authoritative context. Auxiliary Python 3.12+ scripts handle deterministic tasks (frontmatter validation, RTM generation, linting, readiness diagnosis, harness validation, catalog checks, and adapter compliance). Output is modular per .gxp-dev.yaml manifest: target-system specs + code + tests + docs + optional compliance bundle for regulated audits.
If specifications are structured Markdown + YAML frontmatter with stable canonical IDs and explicit downstream mapping, then:
| Property gained | How it works |
|---|---|
| AI-grounded | Target-system specs in YAML+Markdown with stable IDs become authoritative context for any LLM. Anti-hallucination: the agent reads URS-FUNC-001 instead of inventing. |
| Versionable in Git | True diffs between revisions, full history, blame per requirement. |
| Parseable by scripts and AI | Frontmatter is YAML, body has predictable structure (numbered sections, ID-prefixed tables). |
| Traceable automatically | A grep of URS-FUNC-001 shows every reference across URS, FS, DS, IQ, OQ, PQ. No more Excel matrix. |
| Generable downstream | FS.md can be skeletoned from URS.md because outputs are declared in frontmatter and IDs cascade. |
| Validatable across layers | A skill gdd.trace.validate checks coherence URS↔FS↔RA↔Tests programmatically. |
| AI co-authorable | LLMs read structured specs, propose requirements, draft FS sections, flag inconsistencies — humans approve. |
| Diffable for inspection | Auditor reads git diff v1.0..v1.1 specs/URS.md and sees exactly what changed and why. |
The framework does not change the regulations. GAMP 5, 21 CFR Part 11, EU GMP Annex 11 and Annex 22 remain the compliance contract. What changes is how compliance is executed: from static documents to executable specs.
One target-system idea → URS (interview) → RA-INIT (initial risk) → FS (drafted from URS) → RA-DET (FMEA from URS+FS) → Test specs (IQ/OQ/PQ drafted from RA + FS) → Approved work item → Plan Doctor → Code/evidence loop → Compliance bundle (assembled from all of the above).
Each step: AI proposes a draft; human reviews; status advances draft → in-review → approved. The specs are the contract for the target system; the toolkit is the machinery that creates, cascades and verifies that contract. The agent uses those approved specs as authoritative context throughout, eliminating hallucination loops.
This cascade is also the anti-vibe-coding defense: at every stage the agent is grounded in approved upstream content, citations are pre-existing in the templates (not invented), implementation is gated by a work item and plan doctor, and traceability is computable instead of hand-curated.
gxp-driven-dev/
├── README.md ← This file
├── LICENSE ← Apache License 2.0
├── NOTICE ← Apache 2.0 attribution notice
├── STATE.md ← Living memory of toolkit development (maintainer-local, git-ignored — not in a clone)
├── MEMORY.md ← Durable lessons (traps, fixes) — auditable, in-Git
├── AGENTS.md ← AI-agent contract — THE single source
├── CLAUDE.md ← one line: @AGENTS.md (Claude Code import; never edit directly)
├── .gitignore
├── docs/
│ ├── methodology.md ← Why pharma-grade rigor for general software dev
│ ├── project-layout.md ← Canonical layout for consumer projects + .gxp-dev.yaml schema
│ ├── harness-architecture-v2.md ← Dual-harness architecture (ADR-003) — authoritative
│ ├── harness-architecture.md ← Legacy V1 single-harness model (deprecated; migration only)
│ ├── decisions/ ← ADRs (ADR-001 dossier, ADR-002 lifecycle, ADR-003 dual harness)
│ ├── catalog.md ← Generated inventory of templates, skills, scripts, adapters, examples
│ ├── adapter-compliance.md ← Generated adapter parity/compliance status
│ ├── inspirations.md ← Adoption matrix Cat 0/A/B/C/D from 4 reference frameworks
│ ├── requirement-id-scheme.md ← 22 canonical category acronyms + format <DOC>-<CAT>-<NNN>
│ └── canonical-schemas.md, v-model.md, glossary.md
├── templates/csv/ ← 33 canonical templates (acronym-named)
│ └── *.md ← 33 canonical template files
├── patterns/ ← reusable cross-cutting patterns
├── skills/ ← AI-callable skills (Claude Code first)
│ ├── README.md
│ ├── _scripts/ ← Python 3.12+ auxiliary scripts
│ └── <skill-name>/SKILL.md
├── examples/ ← worked end-to-end cases
└── .github/ ← CI workflows
| Family | Templates |
|---|---|
| Master | VMP |
| Concept / Planning | GXP-ASSESS · VP · SUP-ASSESS · RA-INIT |
| Project — Specification | URS · FS · CS · DS · API-SPEC · DBS · UC · AC · ADR |
| Project — Detailed Risk | RA-DET |
| Project — Verification | IQ · OQ · PQ · UT-PLAN · IT-PLAN · SEC-TEST · PERF-TEST · CR · RTM |
| Project — Closeout / Operation | VR · RN · DEPLOY-RUN · PR · CC · IR |
| Retirement | DECOM-PLAN |
| Cross-cutting (conditional) | DPIA · INFRA-QUAL |
The generated inventory in docs/catalog.md is the
machine-checkable source for current counts.
| Skill | Status | Role |
|---|---|---|
gdd.start |
Operative | Zero-state front door — asks how to begin, runs the criticality lane advisor (Lane A cascade / Lane B dev harness), routes to init/next/lifecycle |
gdd.urs.from-idea |
Operative | Interactive interview → specs/URS.md |
gdd.clarify |
Operative | Resolve [NEEDS CLARIFICATION] markers by grilling; never edits presets or promotes status |
gdd.fs.from-urs |
Operative | Draft specs/FS.md from approved URS |
gdd.ra.from-urs |
Operative | Initial Risk Assessment (GAMP 5 §M3 step 1) |
gdd.ra.detail.from-urs-fs |
Operative | Detailed RA / FMEA from URS+FS |
gdd.tests.from-ra |
Operative | Draft IQ/OQ/PQ from RA + FS |
gdd.cs.from-fs |
Operative | (Cat 4 only) Configuration Spec from FS |
gdd.trace.validate |
Operative | Derive RTM, report gaps URS↔FS↔RA↔Tests |
gdd.lint.spec |
Operative | Validate frontmatter + check [NEEDS CLARIFICATION] markers |
gdd.doctor |
Operative | Read-only readiness diagnosis for toolkit, project, or both |
gdd.plan.doctor |
Operative | Work-item readiness check; writes PLAN-DOCTOR.md |
gdd.verify.harness |
Operative | Validate work-item harness state, readiness, plans, loop checkpoints, and evidence |
gdd.implement.from-specs |
Operative | Implement one approved work item from specs + implementation plan; writes run checkpoints when enabled |
gdd.review |
Operative | Independent review; checks implementation evidence and run checkpoints without editing code |
gdd.dev.next |
Operative | Route the active development WI-* item |
gdd.dev.lifecycle |
Operative | Show development lifecycle, evidence coverage, blockers, and validation-ready handoff |
gdd.dev.design-options |
Operative | Write design options and selected direction for a development slice |
gdd.dev.research-slices |
Operative | Write research slices and isolated research review before implementation planning |
gdd.dev.implement |
Operative | Namespaced development implementation command for one planned slice |
gdd.dev.debug |
Operative | Feedback-loop-first diagnosis for a bug in an in_progress slice |
gdd.dev.review |
Operative | Namespaced independent review command for one evidence-ready development slice |
gdd.init |
Operative | Bootstrap a new consumer project from manifest |
gdd.next |
Operative (orchestrator) | Suggest next skill based on STATE + manifest |
gdd.lifecycle |
Operative (orchestrator) | Full-cascade orchestration |
gdd.val.next |
Operative | Route the active validation VI-* item |
gdd.val.lifecycle |
Operative | Show validation lifecycle, gaps, and package readiness |
gdd.val.assess-system |
Operative | Write intake, system analysis, and GAMP assessment |
gdd.val.gap-report |
Operative | Produce/update validation gap report |
gdd.val.report |
Operative | Produce/update validation report from actual evidence |
gdd.val.package |
Operative | Assemble validation package index |
Auxiliary scripts (Python 3.12+ stdlib + PyYAML in skills/_scripts/): validate-frontmatter.py · generate-rtm.py · check-clarification-markers.py · lint-spec.py · doctor.py · validate-harness.py · transition-harness-state.py · validate-catalog.py · validate-adapters.py · lib/gdd_common.py · lib/path_safety.py.
The harness can require TDD evidence for custom-code work items:
red -> green -> refactor is recorded in implementation evidence, while
IQ/OQ/PQ remain the validation layer.
The harness can also require plan-doctor readiness and run tracking:
PLAN-DOCTOR.md gates implementation readiness, loop-state.md records the
active loop, and sequential RUN-*.md files preserve mini-loop checkpoints.
- ❌ Not an eQMS or DMS. Does not manage the runtime lifecycle (workflow execution, approval routing, retention scheduling). Use TrackWise / Veeva Vault QA / MasterControl for that.
- ❌ Does not replace qualified electronic signatures. Produces the content; the signature is applied by your corporate 21 CFR Part 11–compliant signing system.
- ❌ Not vendor-specific. Agnostic to Empower / Chromeleon / LabWare / SAP / TrackWise / Veeva.
- ❌ Does not certify anything. Templates are inputs to validation; regulatory accountability remains with the consumer's Quality Unit.
- ❌ Not an automatic translator. Templates ship in English; instantiation in other languages is human work (AI-assisted if desired).
- ❌ Not a GAMP 5 course. Assumes familiarity with the framework. For learning, consult ISPE GAMP 5 Second Edition (2022) directly.
- ❌ Not a substitute for critical thinking. AI automates paperwork, not judgment. A system owner remains accountable for whether a control is appropriate for a given risk.
- ❌ Not the product being specified. URS/FS/DS/IQ/OQ/PQ instances belong to the target system in the consumer project. Do not write a URS for
gxp-driven-devunless the toolkit is explicitly being treated as a separate target system in a meta-validation project. - ❌ Not a competitor to ISPE GAMP 5. It is an implementation companion inspired by the framework, intended to make rigorous spec-driven development more accessible.
- ❌ Not a clone of
github/spec-kit. We speak a different language — see Positioning below.
| Audience | How they use the toolkit | Value they obtain |
|---|---|---|
| Pharma-IT consultant developing software for regulated clients | Apply the toolkit per client project; AI agents draft specs and code while the consultant reviews and signs off | Sell rigor, not Word templates; faster project delivery; portable methodology |
| Indie founder in a regulated industry | Bootstrap an inspection-ready SDLC in days instead of months | Don't reinvent the V-Model; arrive at first audit aligned with framework expectations |
| R&D lab building internal tooling with AI | Instantiate templates for each tool; cascade through the lifecycle | Reproducible, traceable, low-friction tooling that survives team turnover |
| Enterprise tooling team | Adopt the toolkit for internal B2B tools that need to clear procurement security reviews | SOC 2 + ISO 27001 alignment evidence as side-effect of normal development |
| CSV manager modernizing practice | Replace Word document chains with versionable Markdown specs co-authored with AI | 60-80% less time on paperwork; automatic traceability |
| Auditor / regulatory inspector | Read auto-generated traceability reports; consult Git diffs between approved versions | Audit structural coherence, not manually reconstructed binders |
| GAMP 5 educator / trainer | Use templates + worked examples as didactic material | Modern teaching material (Markdown + Git + AI assistants) instead of legacy Word screenshots |
github/spec-kit is general-purpose spec-driven development for app developers — broad audience, lightweight conventions, brilliant adapter system across 30+ runtimes.
gxp-driven-dev is specialized for environments where spec quality matters at audit grade: regulated industries, R&D labs, enterprise tooling consultancies. Different audience, different vocabulary, complementary not competing.
We borrow from spec-kit: [NEEDS CLARIFICATION] markers, the cross-artifact analyze concept, the slash command namespace pattern, and the runtime adapter philosophy.
We add: typed YAML frontmatter (vs [BRACKET] placeholders), V-Model lifecycle as default (with Agile as opt-in), GAMP-grade traceability with RTM as a derived first-class artifact, 22 canonical category acronyms producing stable <DOC>-<CAT>-<NNN> IDs across the lifecycle, compliance bundles as a free byproduct, multi-industry anchors (pharma + medical-device + finance + aerospace + nuclear + general), and rigor levels (light/standard/strict/regulated).
Both projects can coexist in the same ecosystem. If you don't need pharma-grade rigor, use spec-kit. If you do (or you're in any domain where audit-readiness matters), gxp-driven-dev is the specialized companion.
The toolkit has three layers, deliberately separated so an AI agent can read and reason about each independently:
Markdown files with rich YAML frontmatter. Each template:
- Declarative: declares its
placeholders,presets,validation_rules,inputs,outputs,instance_frontmatter_spec. - Self-describing: embeds an Instantiation flow section at the bottom — interview order, stop criteria, status transitions, downstream mapping.
- Versioned:
template_versionfield (semver) within the toolkit.
Example frontmatter (excerpt from URS.md):
template_id: "URS"
template_version: "0.1.0"
v_model_phase: requirements-definition
gamp_categories_applicable: [2, 3, 4, 5]
inputs:
- template_id: "GXP-ASSESS"
required: true
outputs:
- artifact: "URS instance (Markdown)"
consumed_by: ["FS", "RA-INIT", "IQ-test-cases"]
placeholders:
system_name: { type: string, required: true, … }
gamp_category: { type: enum, values: [1, 3, 4, 5], required: true }
presets:
URS-EREC: { description: "12 reqs of 21 CFR Part 11 Electronic Records", activation_question: "…" }
validation_rules:
- "If gamp_category == 5: URS-DEVENV, URS-QUAL, URS-TRAIN must each have ≥3 requirements"Reusable design patterns referenced from multiple templates and skills (FMEA, V-Model deliverables, GAMP-category applicability, System criticality, Constitution, Spreadsheet fixed tests) plus the engineering-craft patterns adopted from mattpocock/skills (Code review axes, TDD craft, Grilling, Living documentation — see ADR-004).
AI-callable skills that operate on templates and produce instances, validation
reports, readiness diagnoses, or harness evidence. Designed for Claude Code
first; OpenAI Codex is at full parity for the current skill set under
adapters/codex/, with a Cursor reference port (adapters/cursor/). Auxiliary
scripts in Python 3.12+ handle deterministic tasks.
Every requirement is identified as <DOC-TYPE>-<CATEGORY>-<NNN>. Full spec in docs/requirement-id-scheme.md — that file is the canonical source; if this summary drifts from it, the scheme file wins (edit there, not here).
The 22 canonical categories:
| Code | Meaning | Code | Meaning |
|---|---|---|---|
FUNC |
Functional | OPS |
System Operations |
PERF |
Performance | DOCS |
Documentation |
QUAL |
Quality (process) | TEST |
Testing |
TRAIN |
Training | DELIV |
Deliverables / Scope of supply |
DEVENV |
Development environment | PERIPH |
Peripherals |
DATA |
Data structure | HW |
Hardware |
FLOW |
Data flow | EREC |
Electronic Records (21 CFR Part 11) |
REPORT |
Reports / Printouts | ESIG |
Electronic Signatures (21 CFR Part 11) |
SEC |
Security | ||
PROC |
Process organization | ||
UI |
User Interface | ||
API |
Interfaces / APIs | ||
MIGR |
Data Migration | ||
ARCH |
Archiving |
Examples: URS-FUNC-001 (User Requirement #1 functional), FS-API-002 (Functional Spec #2 API), DS-DATA-005 (Design Spec #5 data structure), IQ-TC-042 (IQ test case #42), RA-INIT-001 (Initial RA finding #1).
Consumers with internal naming conventions can opt out via id_scheme: custom + custom_alias in .gxp-dev.yaml.
The toolkit covers the full V-Model lifecycle (ISPE GAMP 5 §3.2 Figure 3.3) and accommodates Agile variants (§3.2 Figure 3.4). Each template's frontmatter declares its v_model_phase and downstream consumers.
Requirements Definition Performance Qualification (PQ)
↓ ↑
URS (top) ───tests───→ PQ
↓ ↑
Functional Specification ───tests───→ OQ
FS (middle) ↑
↓ ↑
Design Specification ───tests───→ IQ
DS (bottom, Cat 5)
(CS for Cat 4 alternates here)
Cross-cutting throughout: VMP, GXP-ASSESS, VP, SUP-ASSESS, RA-INIT, RA-DET, CR (Cat 5), RTM. Cross-cutting conditional: DPIA (plus planned, not yet shipped: CYBER-RA, AISC, P11M, SVP). Lifecycle close: VR, RN, DEPLOY-RUN. Operation: PR, CC, IR (plus planned: CONFIG-BL, UAR, BRR). Retirement: DECOM-PLAN (plus planned: RETIRE-REPORT).
Two supported layouts (full detail in docs/project-layout.md):
Clone-and-go (primary) — your project root IS the template clone (see
Getting started). .gxp-dev.yaml, specs/, work/,
evidence/, and your src/ are created at the clone root, next to the vendored toolkit
machinery (skills/, templates/, .claude/, .codex/ — read-only, upgraded by pulling
upstream).
Standalone — the toolkit lives elsewhere on disk and the consumer repo carries only its own
files; skills are pointed at manually (<gdd-path> = the toolkit root). That repo follows this
layout:
my-project/
├── README.md
├── .gxp-dev.yaml ← manifest
├── pyproject.toml / package.json ← stack-specific
├── src/ ← application code
├── tests/ ← functional tests
├── specs/ ← ⭐ instantiated specs (acronym-named)
│ ├── URS.md FS.md DS.md RA-INIT.md RA-DET.md
│ ├── IQ.md OQ.md PQ.md RTM.md VR.md
│ └── …
├── evidence/ ← IQ/OQ/PQ evidence captured
│ ├── iq/ oq/ pq/ periodic-review/
│ └── agent-runs/<WI-ID>/ ← implementation/review evidence + loop checkpoints
├── work/<WI-ID>/ ← implementation plan + plan doctor readiness
├── compliance-bundle/ ← (optional) assembled for audit
└── .github/workflows/
├── gdd-lint.yml ← CI: frontmatter, broken-link, anti-leak grep
└── trace-check.yml ← CI: URS↔FS↔RA↔Tests coherence
The specs/ folder is the spec documentation of the consumer system. Instances are version-controlled in Git; amendments to approved specs emit new semver versions, mark previous as superseded, never overwrite history.
Declarative file at the root of the consumer's repository. Full field reference in docs/project-layout.md and formal schema in docs/canonical-schemas.md — those are the canonical sources; the example below is an illustrative summary (edit there, not here).
gxp_dev_version: ">=0.1.0,<1.0.0"
project_id: "PROJ-2026-001"
project_name: "Lab Data Capture App"
language: en
mode: develop # develop | validate | hybrid
lifecycle: v-model # v-model | agile | hybrid
gamp_category: 4
lifecycle_phase: project
id_scheme: canonical # canonical | custom
custom_alias: # only when id_scheme == custom
URS: "REQ-USER-DOC"
profile: pharma # pharma | medical-device | finance | aerospace | nuclear | general
rigor_level: standard # light | standard | strict | regulated
presets:
part11_active: true
annex11_active: true
gdpr_active: false
annex22_active: false
templates_active:
- VMP
- GXP-ASSESS
- VP
- URS
- FS
- DS
- ADR
- RA-INIT
- RA-DET
- IQ
- OQ
- PQ
- RTM
- VR
outputs:
specs: true
code: true # AI agent generates from approved specs
tests: true
compliance_bundle: true
default_harness: development # development | validation
harnesses:
development:
enabled: true
lifecycle: agile
evidence_mode: validation_ready
max_active_work_items: 1
tdd:
enabled: true
required_for_statuses: [evidence_ready, reviewed, done]
require_red_green_refactor: true
allow_not_applicable: false
plan_doctor:
enabled: true
run_tracking:
enabled: true
isolation:
enabled: false
mode: metadata_only
active_work_item: null
work_items: []
gates:
design_options: required
research_review: required
implementation_review: required
flow_evidence: when_applicable
validation:
enabled: false
lifecycle: gamp5
source: development_evidence
active_validation_item: null
validation_items: []
# Legacy single-harness block, still supported during migration.
harness:
enabled: true
max_active_work_items: 1
human_gate: spec_ready
tdd:
enabled: true
required_for_statuses: [review, done]
require_red_green_refactor: true
allow_not_applicable: false
plan_doctor:
enabled: true
run_tracking:
enabled: true
isolation:
enabled: false
mode: metadata_only
active_work_item: null
work_items: []- Pre-public-release hardening.
- 33 template files are present under
templates/csv/; current inventory is generated indocs/catalog.md. - 29 skills are present under
skills/, including readiness diagnosis, plan doctor, implementation, review, trace, lint, harness verification, and namespaced development/validation harness commands. - Codex prompt adapters are at full parity for the current skill set; Cursor remains a reference port.
examples/role-harness-dmsexercises the V2 development harness with design options, selected direction, thin specs, research review, run tracking, TDD evidence, flow evidence, and independent review.examples/temp-logger-gmp-chamberexercises the V2 validation harness throughprotocol_generationfor a configured GAMP Category 4 system; it does not claim executed protocol/package readiness.- ADR-003 split the operational model into a development harness and a validation harness; scripts now support both V2 lanes while legacy
harness:remains compatible.
| Milestone | Scope |
|---|---|
v0.7.0 |
Readiness doctor + plan doctor + run tracking + catalog and adapter compliance gates |
v0.8.0 |
Documentation polish, second worked example, and public-release review |
v1.0.0 |
Feature-complete, externally documented, community-ready public release |
v2.0.0 |
Community contributions integrated; coverage of additional regulatory regimes (medical devices ISO 13485 / IEC 62304, aerospace DO-178C, automotive ISO 26262) |
- Integration with corporate eQMS (TrackWise / Veeva / MasterControl) via export adapters and
/gdd.export-to-eqmsskill. - Automated test scaffolding — generate
pytest/Playwright/Viteststubs from approved OQ/PQ test cases. - Multilingual instances — same canonical IDs, body translatable; AI-assisted with human approval.
- Inspector mode — read-only view optimized for FDA / EMA / regional inspectors with auto-generated traceability narrative.
- Continuous compliance — CI checks for drift between approved specs and running application behavior.
- Target-system specifications as executable contracts, not narrative documents.
- Machine-readable frontmatter declares structure; body provides human-readable content.
- Stable canonical IDs survive the full lifecycle — never reused, never deleted, only struck through if obsolete.
- Anti-leak hygiene: nothing in this toolkit references any specific corporate identity, document code, site code or proprietary scheme.
- AI-agnostic by construction: any sufficiently capable LLM consumes the templates and skills; no Claude-only or GPT-only features.
- Regulations are the contract; the toolkit is the implementation. We never claim to override GAMP 5, Part 11, Annex 11 or Annex 22.
- Critical thinking is irreducible. The toolkit automates paperwork; humans remain accountable for judgment.
- Versionable in Git. Diffs between revisions are first-class; history is never overwritten.
- Composable downstream. Each template's output is structured so the next layer auto-drafts from approved upstream.
- Optimize for inspection-readiness. The chain must be auditor-friendly out of the box.
- ❌ A toolkit that only works with one AI assistant. Agnosticism is non-negotiable.
- ❌ A "dead" repo of static templates that don't evolve with regulatory updates.
- ❌ A commercial product disguised as open-source (free today, paywall tomorrow).
- ❌ A toolkit dependent on any single person. Must survive maintainer changes.
- ❌ A replacement for critical thinking about the software under development.
- ❌ A clone of
github/spec-kitwith a regulatory sticker. We are independent and audit-grade-native.
Currently in solo authoring phase (pre-v0.5.0). External contributions will open as the toolkit stabilizes.
If you are a pharma-IT consultant, developer, auditor or open-source enthusiast and you want to follow or eventually contribute:
- Open an issue with your use case, the pain point you want addressed, or a regulatory clarification you need.
- Star and watch the repo (once it is public).
- Share with peers in your organization who deal with regulated software daily.
When external contributions open (planned around v0.5.0 → v1.0.0), we will provide a CONTRIBUTING.md with templates for issues, PRs, new templates, new patterns and new skills.
This project would not exist without the work of the broader open-source software and regulated-industries communities. Explicit inspirations (full details in docs/inspirations.md):
- github/spec-kit — the Constitution pattern,
[NEEDS CLARIFICATION]markers, cross-artifact analyze concept, slash command namespace, runtime adapter philosophy. - gsd-build/get-shit-done — STATE.md living-memory pattern, four canonical gate types (Confirm / Quality / Safety / Transition), fresh-context-per-agent spawn pattern, slopcheck against package hallucinations.
- bmad-code-org/bmad-method — named-agent personas concept, CSV-based help router for skill discovery, Diátaxis docs structure.
- buildermethods/agent-os — lightweight index-as-router pattern, profiles-with-inheritance approach.
- mattpocock/skills (MIT) — the engineering-craft layer: two-axis code review + Fowler smell baseline, TDD craft, grilling, living documentation, feedback-loop-first debugging, and the skill-authoring doctrine (predictability as the root virtue). Adapted portions are credited under its MIT License in
THIRD-PARTY-NOTICES.md; see ADR-004.
On the regulatory and methodological side:
- ISPE GAMP 5 Second Edition (2022) — the foundational framework.
- FDA 21 CFR Part 11 — Electronic Records / Electronic Signatures.
- EU GMP Annex 11 (2025 consultation) and Annex 22 (2025 consultation).
- ICH Q9 (R1) — Quality Risk Management.
- PIC/S PI 041-1 — Data Integrity.
- ISO/IEC 12207 — Software lifecycle processes.
- OWASP ASVS — Application Security Verification Standard.
- ISO 25010 — Software product quality model.
Licensed under the Apache License 2.0 — see LICENSE and NOTICE.
Apache 2.0 was chosen (over MIT, CC0 and a dual Apache+CC-BY-SA arrangement) for three reasons specific to this toolkit: (1) a single permissive license lets the templates be instantiated inside consumer projects — including proprietary, regulated ones — without contaminating them (a share-alike clause on the templates would have been disqualifying for the primary use case); (2) the explicit patent grant matters to the enterprise/pharma legal teams who are the primary audience; (3) the NOTICE-file attribution preserves credit. The full rationale is recorded in the project memory and STATE.md.
Authored as a personal initiative to bring spec-driven development methodology to AI-assisted software construction, anchored on published international standards (GAMP 5 / EU GMP / FDA 21 CFR Part 11), and to give the open-source community a foundation upon which to build the next generation of compliant, AI-native software tools.