Project_Velocity/.Agent Context/Sprint 1/Biomimetic Agentic Orchestration Layer/Prompt Master, Librarian, and Researcher Role Spec.md

Prompt Master, Librarian, and Researcher Role Spec

Date: 2026-04-14
Status: Draft implementation artifact
Purpose: Define the three highest-leverage role systems inside the colony so their behavior is deterministic, governable, and implementable without ad hoc interpretation.

1. Purpose

The planner, prompt master, librarian, and researcher chain is where colony quality is won or lost. If this layer is vague, workers receive inconsistent context, external evidence quality collapses, and the final review stage becomes overloaded.

This document defines the exact role boundaries for:

• prompt master
• librarian
• researcher

2. Why These Roles Need a Separate Spec

These roles are special because they shape every downstream worker.

Workers may be numerous and disposable. These three roles are not. They are multiplier roles:

• prompt master multiplies task clarity
• librarian multiplies internal retrieval quality
• researcher multiplies external evidence quality

If these roles are weak, adding more workers only scales confusion.

3. Prompt Master

3.1 Purpose

Convert planned tasks into execution-grade prompt packages.

3.2 Inputs

• mission envelope
• task graph
• mission budgets
• mission risk class
• domain adapter metadata
• template registry
• exemplar registry

3.3 Outputs

• one prompt_package per executable task
• optional prompt package for aggregator
• optional prompt package for reviewer

3.4 Required Behavior

The prompt master must:

• select the right prompt structure by mission type and role type
• bind explicit success criteria from the task graph
• encode tool limits in the prompt package metadata, not only in prose
• choose a model route appropriate for the task
• distinguish between task instructions and domain context
• keep prompts concise enough to preserve budget for retrieval and evidence

3.5 Forbidden Behavior

The prompt master must not:

• invent data access beyond the librarian pass
• hide approval requirements inside free-form prose
• issue direct write instructions to workers
• collapse multiple tasks into one giant prompt for convenience

3.6 Acceptance Criteria

• every executable task has a prompt package
• every prompt package references its task_id
• every prompt package declares a model route and tool scope
• packages are reproducible from the same inputs

4. Librarian

4.1 Purpose

Convert mission context and task intent into scoped internal access guidance.

4.2 Inputs

• mission envelope
• task graph
• prompt packages
• domain source catalog
• tenant and actor scope
• cache index

4.3 Outputs

• one librarian_pass per worker task
• optional route cards for aggregator and reviewer

4.4 What a Librarian Pass Must Contain

• pass_id
• mission_id
• task_id
• resource_families
• allowed entity IDs when relevant
• recommended retrieval order
• summary snippets
• freshness hints
• expiry time if needed

4.5 Required Behavior

The librarian must:

• narrow context, not widen it
• prefer route cards over raw data dumps
• separate mandatory sources from optional sources
• tell the worker where evidence likely lives
• surface cached snippets when available

4.6 Forbidden Behavior

The librarian must not:

• copy entire datasets into worker context
• silently elevate data access
• assume all workers need all sources
• become a general-purpose reasoner

4.7 Acceptance Criteria

• workers can locate domain evidence without broad data flooding
• passes are task-specific
• sensitive scopes are explicit and auditable

5. Researcher

5.1 Purpose

Gather and normalize external evidence for tasks that require web or browser-based research.

5.2 Inputs

• mission envelope
• task graph
• researcher-designated task objectives
• tool policy decisions
• search provider configuration
• browser provider configuration

5.3 Outputs

• research_artifact objects with normalized citations

5.4 Required Behavior

The researcher must:

• search only when policy permits
• produce citations with source URL, title, provider, and retrieval timestamp
• separate observed evidence from inferred interpretation
• include enough provenance for reviewer audit
• support both search-engine retrieval and browser-based extraction

5.5 Forbidden Behavior

The researcher must not:

• claim unsupported facts
• inject uncited claims into downstream workers
• access blocked public-web domains
• decide writeback actions

5.6 Acceptance Criteria

• every research artifact contains normalized citations
• policy-blocked research requests fail clearly
• downstream workers receive research packets in a stable format

6. Handshake Contract Between the Three Roles

Fixed sequence:

1. planner creates task graph
2. prompt master emits prompt packages
3. librarian emits passes
4. researcher emits external evidence when required
5. worker execution starts only after the required packets exist

Required join key:

• mission_id
• task_id

Required invariant:

No worker should execute unless the following minimum packet exists:

• prompt package
• librarian pass
• policy decision for required tools

For research tasks, research artifacts are also required.

7. Operational Metrics

Track these role-level metrics:

• prompt package reuse rate
• average prompt package size by mission type
• librarian pass hit rate
• retrieval miss rate
• average research citation count
• reviewer rejection rate caused by weak prompting
• reviewer rejection rate caused by weak evidence

8. Ticket Breakdown

1. implement prompt template registry
2. implement exemplar registry
3. implement prompt package builder
4. implement source catalog
5. implement route-card builder
6. implement cache index
7. implement search provider normalization
8. implement browser provider normalization
9. integrate role outputs into worker launch contract

9. Bottom Line

Prompt master, librarian, and researcher are not helper utilities. They are the colony’s quality-control spine before execution. Their contracts must be explicit from the first implementation pass.