Library Architecture: Namespacing, Versioning, Access Patterns

A prompt library is not a folder of markdown files. It is a queryable registry that maps agent identities, task types, environments, and model targets to specific versioned prompt artifacts. The library's architecture determines whether your team can answer the infrastructure test questions from Lesson 1 — or whether they are guessing.

Namespacing is the foundation. Every prompt in the library belongs to a namespace that encodes its context: who owns it, what it governs, and where it runs. A flat naming scheme — AGENT-X-system-message.md — breaks down the moment you have three variants: one for development, one for staging, and one for production. Add model variants and you have nine files with no enforced relationship. A structured namespace solves this at the library level.

// Namespace schema: {agent}/{environment}/{variant}/{version}
//
// Examples:
//   forge/prod/system/1.4.0
//   forge/staging/system/1.5.0-beta
//   clawmander/prod/system/2.1.0
//   clawmander/prod/handoff/1.0.2
//   drill/prod/system/3.0.0
//   drill/prod/onboarding/1.2.0
//
// Resolution order (most specific wins):
//   1. {agent}/{environment}/{variant}/{version}   — pinned version, exact env
//   2. {agent}/{environment}/{variant}/latest       — latest tested for env
//   3. {agent}/prod/{variant}/latest               — prod fallback
//
// Metadata required on every registered prompt:
//   owner:        agent name or team slug
//   created:      ISO date
//   last_tested:  ISO date
//   model_target: claude-sonnet-4-6 | claude-opus-4-6 | *
//   token_budget: max expected input tokens
//   schema_ref:   output schema filename (required if structured output)

Versioning follows semantic versioning conventions adapted for prompts. A MAJOR version increment signals a breaking change to output structure — any downstream consumer must be updated. A MINOR version increment adds capability without changing existing output fields. A PATCH version increment fixes a behavior defect without changing scope or structure. Teams that skip versioning and track prompts by filename are one model update away from a silent production incident.

Access patterns matter as much as the library structure. The application layer should never embed a prompt string directly. It should resolve a prompt reference — a namespace path — at runtime or at build time, depending on the deployment model. This decoupling means you can hot-swap a prompt version in staging without touching application code, and you can roll back a production prompt without a full redeployment.

1. Step 1: Define Your Namespace Schema Choose a namespace schema that encodes agent, environment, and variant as separate path segments. Enforce it as a registry constraint — reject any prompt registration that does not conform. Document the schema in your CLAUDE.md or equivalent central configuration.
2. Step 2: Register All Existing Prompts Audit every system message, user-turn template, and few-shot block currently in production. Register each one with owner, created date, model target, and output schema reference. If you cannot determine the created date, use today — and flag the prompt for an immediate regression test to establish a baseline.
3. Step 3: Implement Prompt Resolution Build a resolution function that accepts a namespace path and returns the prompt string and its metadata. The function handles environment fallback (staging → prod), version pinning for critical paths, and cache invalidation when a new version is registered. This function is the single access point for all prompt retrieval in the application.
4. Step 4: Establish the Change Gate No prompt enters the library without passing through the change gate: author, reviewer, test run results, and the specific version string assigned. The change gate is where "I updated the system message" becomes "forge/prod/system/1.4.1 was approved by FORGE, tested against the regression suite on 2026-03-02, and promoted to staging." One is a hallway conversation. The other is an audit trail.