Component Sharing Architecture: coditect-core <-> BIO-QMS

Date: 2026-02-15 Author: Claude (Opus 4.6) Project: BIO-QMS Context: User requested research on how to create supporting CODITECT components (skills, commands, scripts, hooks, workflows) in coditect-core for each BIO-QMS agent, specifically asking about symlinks vs copies.

---

1. The Question

"Create all of the corresponding skills commands scripts hooks workflows in coditect-core to support each of the BIO-QMS agents as they get created. These should be created in coditect-core and can be a symlink to the component required in BIO-QMS or should we copy them? I do not like copies but given separate git repositories what is the best solution here?"

2. Current Architecture

rollout-master/                              (orchestrator repo)
├── submodules/core/coditect-core/           (framework — 780 agents, 457 skills)
│   ├── agents/                              generic framework agents
│   ├── skills/                              generic framework skills
│   ├── commands/                            slash commands
│   └── scripts/                             automation
│
└── submodules/dev/coditect-biosciences-qms-platform/  (product repo)
    ├── .coditect -> ~/.coditect             symlink to protected installation
    ├── agents/                              10 product-specific agents
    ├── backend/                             NestJS + Prisma + XState
    └── internal/                            project plans, analysis

Key facts:

• BIO-QMS connects to coditect-core via symlink (.coditect -> ~/.coditect), NOT git submodule
• Both repos are submodules of rollout-master but have no direct git relationship
• BIO-QMS agents are tightly coupled to product domain (FDA, ISO 13485, XState state machines)
• coditect-core agents are generic framework components (no product: field)
• There are zero product-specific agents in coditect-core today

3. Options Evaluated

Option A: Symlinks Within rollout-master

Since both repos are submodules of the same parent, create symlinks:

coditect-core/agents/bio-qms-wo-orchestrator.md -> ../../submodules/dev/coditect-biosciences-qms-platform/agents/bio-qms-wo-orchestrator.md

Pros	Cons
Single source of truth	Git tracks symlinks as text, not targets
User's stated preference	BREAKS on clone — target path is machine-specific
No file duplication	Symlinks across submodule boundaries are fragile
Changes propagate instantly	CI/CD, Docker builds won't resolve cross-submodule symlinks
	platform.db indexer may not follow symlinks

VERDICT: REJECTED — Cross-submodule symlinks break on clone and in CI. The target path ../../submodules/dev/... only works when both submodules are checked out at specific relative paths within rollout-master. Any deployment, Docker build, or independent clone of coditect-core would have dangling symlinks.

Option B: Copy Agents to coditect-core

Duplicate each BIO-QMS agent .md file into coditect-core/agents/.

Pros	Cons
Discoverable by /which	Two copies to maintain — user explicitly rejects this
Works in all environments	Drift between copies
No cross-repo dependency	Unclear which is SSOT
	Bloats coditect-core with product-specific content

VERDICT: REJECTED — User explicitly stated "I do not like copies."

Option C: Product Registry Pattern (RECOMMENDED)

Create framework-level wrapper components in coditect-core that reference BIO-QMS product agents without duplicating their content. The wrappers serve as discovery entries and orchestration glue.

Architecture:

coditect-core/                                   (FRAMEWORK)
├── agents/bio-qms-wo-orchestrator.md           ← Thin registry entry
├── skills/bio-qms-agent-framework/SKILL.md     ← How to use BIO-QMS agents
├── commands/bio-qms-agent.md                   ← /bio-qms-agent command
├── hooks/bio-qms-agent-audit.md                ← Audit hook definition
└── scripts/bio-qms/                            ← Automation utilities

BIO-QMS repo/                                    (PRODUCT — SSOT)
├── agents/bio-qms-wo-orchestrator.md           ← Full agent definition
├── backend/libs/qms-core/src/agents/           ← TypeScript implementation
└── config/system-prompts/                      ← Agent system prompts

How the thin registry entries work:

# coditect-core/agents/bio-qms-wo-orchestrator.md (thin entry)
---
name: bio-qms-wo-orchestrator
type: agent
product: CODITECT-BIO-QMS
product_repo: coditect-biosciences-qms-platform
agent_type: orchestrator
domain:
  - healthcare
  - quality-management
description: >
  Work Order Orchestrator for BIO-QMS. Coordinates multi-agent workflows
  for FDA 21 CFR Part 11 compliant quality management.
  Full definition in product repository.
ssot: product
ssot_path: agents/bio-qms-wo-orchestrator.md
---

# BIO-QMS Work Order Orchestrator

> **Product Agent:** Full definition lives in `coditect-biosciences-qms-platform/agents/bio-qms-wo-orchestrator.md`

## Overview
Multi-agent orchestrator for biotech QMS work orders...

## When to Use
- Work order lifecycle management
- Multi-agent coordination for QMS workflows
- FDA-compliant quality event processing

## See Also
- Product repo: `submodules/dev/coditect-biosciences-qms-platform/agents/`
- Skill: `skills/bio-qms-agent-framework/SKILL.md`
- Command: `/bio-qms-agent`

Pros	Cons
No duplication — SSOT is product repo	Registry entries need maintenance
Discoverable — /which finds agents via registry	Slightly more indirection
Portable — no symlink fragility	Must define "thin entry" convention
Works in CI/CD — no cross-repo deps	New pattern (but simple)
Clear ownership — ssot: product marks authority
Extensible — works for any future product

VERDICT: RECOMMENDED — This is the architecture used by package registries (npm has package.json metadata, not the full source). The thin entry provides discovery and routing while the product repo retains authority.

Option D: npm Package

Package BIO-QMS agents as @coditect/bio-qms-agents and install in both repos.

Pros	Cons
Standard JS pattern	Markdown agents aren't npm modules
Version pinning	Publish/install overhead for .md files
	Overkill for markdown components

VERDICT: REJECTED — Markdown component files don't benefit from npm packaging. This adds ceremony without value.

4. Recommended Architecture: Product Registry Pattern

4.1 What Gets Created in coditect-core

For each of the 10 BIO-QMS agents, create in coditect-core:

Component Type	Location	Purpose	Count
Agent (thin)	agents/bio-qms-*.md	Discovery registry entry	10
Skill	skills/bio-qms-agent-framework/SKILL.md	How to use BIO-QMS agent system	1
Command	commands/bio-qms-agent.md	/bio-qms-agent <name> <task>	1
Hook	hooks/bio-qms-agent-audit.md	Audit trail on agent invocation	1
Workflow	docs/workflows/bio-qms-agent-workflow.md	Agent orchestration workflow	1

Total: 14 new components (10 thin agent entries + 4 supporting components)

4.2 Thin Agent Entry Convention

Each thin entry follows this pattern:

• YAML frontmatter with product:, ssot: product, ssot_path: fields
• Brief description (2-3 paragraphs, not full system prompt)
• "When to Use" section for /which matching
• "See Also" pointing to product repo SSOT
• NO system prompt duplication — the system prompt lives only in the product repo

4.3 The Skill: bio-qms-agent-framework

Teaches Claude how to work with BIO-QMS agents:

• Agent topology (orchestrator, workers, specialists, evaluator)
• Message routing patterns (inbound types -> agent dispatch)
• Circuit breaker behavior (failure thresholds, recovery)
• Token budget management (per-tier allocation)
• Tenant isolation requirements
• Audit trail integration

4.4 The Command: /bio-qms-agent

/bio-qms-agent wo-orchestrator "Process work order WO-2024-001"
/bio-qms-agent capa-investigation "Investigate deviation DEV-2024-015"
/bio-qms-agent compliance-monitoring "Audit preparation check"

Routes to product-specific agent definitions in BIO-QMS repo.

4.5 The Hook: bio-qms-agent-audit

PostToolUse hook that captures agent invocations for FDA Part 11 audit trail.

4.6 The Workflow: Agent Orchestration

Documents the multi-agent coordination flow with Mermaid diagrams.

5. Implementation Plan

Phase 1: Convention (Now)

1. Define ssot: product and ssot_path: frontmatter fields
2. Create the thin agent entry template
3. Document the Product Registry Pattern in an ADR

Phase 2: Create Components (Next)

1. Create 10 thin agent entries in coditect-core
2. Create the bio-qms-agent-framework skill
3. Create the /bio-qms-agent command
4. Create the audit hook and workflow doc

Phase 3: Discovery Enhancement (Future)

1. Extend /which to recognize product: field and show product agents
2. Add product_repo to platform.db schema for cross-repo search
3. Extend component-indexer.py to index product repos

6. Why NOT Symlinks

The user's instinct to avoid copies is correct. But symlinks across git submodule boundaries have these specific failure modes:

1. Git stores symlink targets as text — ../../other-submodule/file.md is stored literally
2. Independent clones break — cloning coditect-core alone leaves dangling symlinks
3. Docker builds break — containers don't have rollout-master's submodule layout
4. CI/CD breaks — GitHub Actions checkout of coditect-core won't resolve cross-submodule paths
5. Protected installation breaks — ~/.coditect (the rsync'd copy) won't have BIO-QMS files

The registry pattern achieves the goal (no duplication of SSOT) without symlink fragility. The thin entry is ~30 lines vs ~150 lines for the full agent — it's metadata, not a copy.

7. Decision

RECOMMENDED: Option C — Product Registry Pattern

• Product agents stay in product repos (SSOT)
• coditect-core gets thin registry entries (discovery + routing)
• Supporting components (1 skill, 1 command, 1 hook, 1 workflow) in coditect-core
• New frontmatter convention: product:, ssot: product, ssot_path:
• Future: extend /which for product-aware discovery

This maintains the user's "no copies" principle while respecting git repository boundaries.