# Epic: Offline-first prompt bank registry and reference API Backlog Item ID: PROMPT-BANK-REGISTRY-EPIC GitHub Issue: GH-338 Lead role: Architect Supporting roles: Product Owner, Security, Developer, QA, Technical Writer Status: groomed ## Epic Story As a platform owner, I want Open Orchestra to maintain a versioned prompt bank that works offline from the repository and can optionally sync categorized references from an external bucket/API, so that agents can retrieve high-quality prompt guidance on demand without bloating skills or requiring internet access for core operation. ## Relationship Parent/related epic: #333 Advisory supervisor for local findings and guarded GitHub worker. This epic complements the advisory and SaaS direction. The advisory supervisor can produce findings that improve prompt bank entries, while the prompt bank registry provides curated guidance that agents can retrieve safely during local or SaaS-backed execution. ## Problem Skills should stay compact and role-scoped. If every diagram, QA, security, architecture, or workflow reference is embedded directly into skills, agent context becomes expensive and hard to govern. If references live only in a SaaS or bucket, local/offline operation breaks. Open Orchestra needs a hybrid model: - a small canonical prompt bank in the repo for offline execution; - external categorized references for richer examples and reusable patterns; - an API/retrieval layer that returns only the minimum relevant guidance; - guardrails that prevent raw prompt injection, secrets, or source-specific content from becoming reusable rules. ## MVP Outcome - Local prompt bank manifest stored in the repo and packaged with the CLI. - Prompt bank entries categorized by role, phase, skill, artifact type, runtime, safety level, and offline eligibility. - Retrieval command/API resolves prompt entries by task intent, role, phase, runtime, tags, and safety filters. - Skills load compact baseline rules first and request prompt bank references only when task context needs them. - External bucket/API contract is documented, optional, and disabled by default. - Offline mode uses the local prompt bank only and records clear deferred evidence when an optional external reference is unavailable. - Promotion workflow prevents advisory findings, raw prompts, source-specific documents, secrets, and prompt-injection content from becoming reusable entries without review. ## To-Be Outcome - SaaS-backed prompt registry with tenant/project categorization, quality scoring, usage telemetry, approval workflows, and API-based retrieval. - Bucket-backed prompt artifacts with signed manifests, checksums, versioning, retention policy, and safe caching. - Advisory supervisor proposes prompt bank improvements as classified findings, but human approval is required before promotion. - Registry supports cross-runtime references for Codex, Claude, Cursor, Copilot, generic agents, and local model runners. ## Architecture Contract The local prompt bank is the source of truth for core runtime behavior. External registries may enrich retrieval, but they must never be required for baseline skills, workflow gates, or local/offline execution. Retrieval flow: 1. Build query signals from task intent, owner role, workflow phase, skill id, runtime target, artifact type, tags, safety level, and offline mode. 2. Load and validate the packaged local manifest. 3. Filter entries by eligibility and safety constraints. 4. Return summaries first, with optional full content only when explicitly requested and still within budget. 5. Attach evidence that identifies entry ids, versions, budgets, skipped unsafe entries, and unavailable optional sources. Budget defaults should be conservative and configurable: - `maxEntries`: default 5, hard maximum 12. - `maxSummaryChars`: default 4000 per response. - `maxFullContentChars`: default 12000 per response. - `maxEntryChars`: default 6000 for an individual entry. - Retrieval must fail closed or truncate with evidence when limits are exceeded. ## Reusable Entry Restrictions Reusable prompt bank entries must be source-free and instruction-safe. Allowed reusable content: - distilled guidance, checklists, schemas, examples, and validation rubrics; - public or internally approved rules that are not tied to a single customer, source document, ticket, provider response, or raw user prompt; - sanitized excerpts that have explicit provenance and approval. Blocked reusable content: - source-specific PDF text, issue comments, business labels, customer names, or project-only narrative copied into generic rules; - secrets, tokens, credentials, environment values, private URLs, PII, PHI, financial data, or regulated data; - raw prompts, raw model responses, chain-of-thought, or provider transcripts; - prompt-injection strings, tool-control instructions, fake policy overrides, shell commands, path traversal strings, or hostile artifacts unless stored as isolated adversarial fixtures with `isExecutableInstruction=false`; - content whose license, ownership, or tenant/project scope is unclear. ## Proposed Child Stories ### GH-338A: Local Prompt Bank Manifest As an agent runtime, I want a local manifest of prompt bank entries so that I can retrieve approved guidance without internet access. Acceptance criteria: - Defines a typed manifest schema with `schemaVersion`, `generatedAt`, `entries`, and manifest-level checksum metadata. - Defines entry fields: `id`, `title`, `summary`, `category`, `roles`, `phases`, `skills`, `runtimes`, `artifactTypes`, `tags`, `safetyLevel`, `offlineEligible`, `sourceFree`, `isExecutableInstruction`, `version`, `status`, `owner`, `path`, `checksum`, `provenance`, and `review`. - Includes initial categories for diagrams, QA evidence, advisory findings, security review, story mapping, runtime coordination, and documentation. - Packages local entries with the CLI and loads them without network access. - Rejects duplicate ids, missing files, checksum mismatch, unsupported schema versions, unsafe status, oversized entries, and non-source-free entries. - Blocks reusable entries containing source-specific text, secrets, raw prompts, provider transcripts, or prompt-injection content. - Includes unit tests for schema validation, manifest loading, checksum validation, offline packaging, and invalid-entry rejection. Suggested size: M. Suggested owners: Architect, Developer, Security, QA. ### GH-338B: Bounded Prompt Bank Retrieval API As a skill loader, I want to retrieve prompt bank entries by runtime need so that skills stay small and context is loaded on demand. Acceptance criteria: - Provides CLI/API retrieval by role, phase, task intent, skill id, runtime, artifact type, tags, safety level, and offline-only mode. - Returns deterministic summaries by default and full content only with an explicit `includeContent` request. - Enforces max entry count, per-entry size, total character/token budget, and configured safety filters before content enters runtime context. - Orders results by exact skill/phase match, role match, runtime match, safety level, local availability, version status, and recency. - Emits evidence showing query signals, entry ids, versions, budgets consumed, skipped entries, truncation, and unavailable optional sources. - Does not fetch external references when offline mode is active. - Fails closed for invalid query values, unsupported runtimes, unsafe entries, corrupted manifests, budget exhaustion, and policy engine failure. - Includes unit and integration tests for query filtering, deterministic ranking, budget enforcement, summary-only defaults, full-content opt-in, offline mode, and evidence emission. Suggested size: M. Suggested owners: Architect, Developer, QA. ### GH-338C: Optional External Registry Contract As a platform operator, I want an external prompt registry contract so that rich references can be stored outside the package without making the package depend on SaaS. Acceptance criteria: - Documents bucket layout, manifest format, entry metadata, checksums, signature strategy, cache policy, retention policy, and fallback behavior. - Defines API endpoints for `search`, `resolve`, `fetch`, `health`, and `version` with request, response, error, pagination, auth, rate-limit, and idempotency expectations. - Requires tenant/project scoping, data residency classification, and least-privilege credentials for SaaS mode. - Requires HTTPS/TLS, signed manifests or equivalent integrity controls, and local cache validation before serving external content. - Makes external retrieval opt-in and records deferred evidence instead of failing local workflows when the registry is disabled or unavailable. - Requires redaction, secret scanning, prompt-injection checks, license/source checks, and safety classification before storing or serving entries. - Includes contract tests using local fixtures for search, fetch, checksum failure, expired signature, unavailable registry, unsafe entry rejection, and offline fallback. Tests must not require network or provider secrets. Suggested size: L. Suggested owners: Architect, Security, Developer, QA. ### GH-338D: Prompt Promotion Workflow As a maintainer, I want prompt bank changes to go through review so that weak or unsafe prompt guidance is not promoted automatically. Acceptance criteria: - Advisory findings can propose prompt entries but cannot promote them directly. - Promotion requires classification, source-free review, safety review, owner approval, QA evidence, and version decision. - Records provenance: source task, finding id, proposer, reviewer, reason, source policy, safety checks, version, checksum, and superseded entries. - Supports statuses `draft`, `review_requested`, `approved`, `active`, `deprecated`, `rejected`, and `quarantined`. - Supports deprecation and rollback without deleting historical provenance. - Blocks promotion of source-specific text, secrets, raw prompts, provider transcripts, prompt-injection content, unclear licenses, and tenant-scoped material unless it is quarantined as a non-runtime fixture. - Emits evidence and review artifacts for approval, rejection, deprecation, and rollback actions. - Includes tests for promotion gates, advisory proposal isolation, required approvals, unsafe-content rejection, rollback, deprecation, and provenance immutability. Suggested size: M. Suggested owners: Product Owner, Security, Developer, QA, Technical Writer. ### GH-338E: Prompt Bank Documentation and Validation Matrix As a maintainer, I want implementation guidance and validation evidence mapped to the prompt bank stories so that teams can implement slices consistently. Acceptance criteria: - Documents local/offline behavior, manifest fields, retrieval flags, external registry opt-in, promotion workflow, and evidence expectations. - Provides examples of safe reusable entries and blocked entries without using secrets, customer text, or raw prompts. - Maps every story acceptance criterion to unit, contract, integration, security, or docs-review evidence. - Documents operator guidance for cache invalidation, external registry downtime, unsafe entry quarantine, and rollback. - Updates public docs only after implementation exposes user-facing commands or APIs. Suggested size: S. Suggested owners: Technical Writer, QA, Product Owner. ## Epic Acceptance Criteria - Child stories are independently executable, estimable, and testable. - Local prompt bank remains the source of truth for core operation. - External bucket/API is optional and never required for baseline skills. - Prompt entries are categorized and retrievable by role, phase, skill, runtime, artifact type, tags, and safety level. - Retrieval is bounded by entry count, per-entry size, and total context budget. - Offline mode avoids network calls and degrades with explicit evidence when optional external references are unavailable. - Source-specific text, secrets, raw user prompts, provider transcripts, and prompt-injection content are excluded or blocked from reusable entries. - Advisory supervisor integration is defined without allowing automatic promotion. - Safety review and validation evidence are required before entries become active runtime guidance. ## Non-Goals - Full SaaS implementation in the first story. - Replacing existing skills with a remote-only prompt system. - Making internet access mandatory for local workflows. - Storing raw prompts, raw responses, provider transcripts, or chain-of-thought by default. - Promoting advisory findings directly into active runtime instructions. - Building a prompt authoring UI in the MVP. - Using external registries as a policy authority for workflow gates. ## Risks - Context bloat if retrieval is not aggressively bounded. - Prompt injection through external registry entries, issue text, lessons learned, generated artifacts, or adversarial examples. - Secret leakage from raw prompts, provider responses, workflow evidence, or copied source documents. - Drift between local prompt bank and external registry. - SaaS dependency creeping into offline workflows. - Unsafe promotion if advisory findings are treated as approved guidance. - Tenant, license, or source-ownership violations if entries are reused across scopes without classification. - Stale local caches serving deprecated or quarantined entries. ## Security And Safety Review Security review is required before implementation because the epic touches prompt injection, secrets, external network retrieval, cache integrity, tenant/project scope, and runtime context assembly. Non-negotiables: - local/offline mode must not require network access; - external registries must use HTTPS/TLS and integrity validation; - all external content is untrusted until validated, scanned, classified, and approved; - raw prompts, raw responses, provider transcripts, secrets, and source-specific content must not become reusable runtime instructions; - prompt-injection examples must be stored only as inert fixtures and never loaded as executable guidance; - retrieval must fail closed when validation, policy, budget, checksum, or cache integrity checks fail; - evidence must identify entry ids and versions without leaking entry content that failed safety checks. ## QA Evidence Strategy Recommended automated coverage: - schema tests for manifest and entry validation; - unit tests for filters, deterministic ranking, and budget enforcement; - contract tests for CLI/API request, response, error, pagination, and evidence shapes; - security tests for secret patterns, raw prompt markers, source-specific text, prompt-injection strings, checksum failures, and invalid cache state; - offline tests proving no network access is required for local manifest load and retrieval; - integration tests with local external-registry fixtures for unavailable registry, unsafe entry, expired signature, checksum mismatch, and fallback; - workflow tests for advisory proposal, approval, rejection, deprecation, rollback, and provenance immutability. Evidence required per implementation story: - exact commands and pass/fail results; - acceptance-criteria-to-evidence matrix; - sample manifest or API fixture with sanitized entries; - retrieval evidence showing budgets, selected ids, skipped ids, and offline behavior; - security review result for external retrieval, cache, promotion, and runtime context changes; - documented deferred risks when optional external registry behavior is not implemented in the current slice. ## Suggested Epic Size L for the groomed epic. MVP slice order: 1. GH-338A Local Prompt Bank Manifest. 2. GH-338B Bounded Prompt Bank Retrieval API. 3. GH-338D Prompt Promotion Workflow. 4. GH-338C Optional External Registry Contract. 5. GH-338E Documentation and Validation Matrix.