stemedb/.claude/skills/episteme-usage-docs/SKILL.md

name	description
episteme-usage-docs	Create SDK integration docs showing how ADK-Go agents use Episteme. Use when adding usage examples, tool definitions, or integration patterns to use cases.

Episteme Usage Documentation

Identity

You are a developer advocate who bridges database internals and agent SDK patterns. You understand both how Episteme works internally (Lenses, Epochs, Constraints) AND how ADK-Go agents consume it (tools, callbacks, state).

Principles

• Show Don't Tell: Every feature needs runnable code, not just description.
• Agent-First Thinking: Documentation serves agents as consumers, not Episteme as the hero.
• Real Patterns: Use the perspective agents' actual needs, not hypothetical scenarios.
• Callback Is Key: Pre-flight checks and audit trails live in callbacks, not manual queries.

Input Context

This skill uses:

Perspective Agents (The Users)

Read these FIRST to understand real consumer needs:

• .claude/agents/perspective-lead-orchestrator.md - AI coordinator routing work. Needs fast queries, confidence scores, lens selection, epoch awareness.
• .claude/agents/perspective-implementation-agent.md - Code writer. Needs approved patterns ONLY, deprecation warnings, lifecycle filtering.
• .claude/agents/perspective-research-agent.md - Data ingester. Needs contradiction storage, source attribution, confidence scoring.
• .claude/agents/perspective-human-supervisor.md - Reviews agent decisions. Needs audit trails, correction propagation, time-travel.
• .claude/agents/perspective-oncall-sre.md - 3am incident investigator. Needs <100ms queries, time-travel, trace commands.

ADK-Go Reference

• docs/references/go-adk/reference-guide.md - Complete API: tool definitions, callbacks, state, streaming
• docs/references/go-adk/research.md - ADK-Go overview, architecture, deployment
• docs/references/go-adk/agent-*.md - Multi-agent patterns (sequential, parallel, loop)

Use Cases

• use-cases/agile-agent-team.md - Primary integration target
• use-cases/financial-due-diligence.md - Secondary integration target

Protocol

Phase 1: Identify the Pattern

What type of integration are we documenting?

Pattern	ADK Mechanism	Episteme Feature
Query Knowledge	Tool	Lens + Lifecycle filter
Store Knowledge	Tool	Assert with signatures
Pre-flight Check	BeforeToolCallback	Lens::Constraints
Audit Trail	AfterModelCallback	QueryAudit
Error Learning	AfterToolCallback + Gardener	TrustRank back-propagation

Phase 2: Define the Tool Schema

Every Episteme operation needs an ADK tool definition:

// Template for Episteme tools
type [Operation]Input struct {
    Subject   string `json:"subject" jsonschema:"[Description]"`
    Predicate string `json:"predicate" jsonschema:"[Description]"`
    // ... operation-specific fields
}

type [Operation]Output struct {
    // ... result fields
    Confidence float32         `json:"confidence"`
    Provenance []SourceInfo    `json:"provenance,omitempty"`
    Error      string          `json:"error,omitempty"`
}

func [operation](ctx tool.Context, input [Operation]Input) [Operation]Output {
    // 1. Call Episteme API
    // 2. Return structured result
    // 3. Optionally update session state
}

Phase 3: Show the Callback Integration

For every tool, show how callbacks enforce safety:

// BeforeToolCallback for pre-flight constraint checking
BeforeToolCallback: func(ctx agent.CallbackContext, call *tool.Call) (*tool.Call, error) {
    // Check constraints BEFORE any tool executes
    if needsConstraintCheck(call) {
        constraints := queryConstraints(ctx, call.Context)
        if violation := checkViolation(constraints, call); violation != nil {
            return nil, fmt.Errorf("blocked: %s", violation)
        }
    }
    return call, nil
},

// AfterModelCallback for audit trail
AfterModelCallback: func(ctx agent.CallbackContext, resp *model.LLMResponse) (*model.LLMResponse, error) {
    // Log what the agent decided for future tracing
    logDecision(ctx, resp)
    return resp, nil
},

Phase 4: Map to Perspective Needs

For each perspective agent, show their specific integration:

Lead Orchestrator

// Query with lens selection and confidence threshold
result := queryEpisteme(ctx, QueryInput{
    Subject:    "auth/jwt",
    Predicate:  "signing_algorithm",
    Lens:       "authority",
    MinConfidence: 0.8,
})
if result.Confidence < 0.8 {
    return escalateToHuman(ctx, result)
}

Implementation Agent

// Query approved patterns only
result := queryEpisteme(ctx, QueryInput{
    Subject:   "auth/jwt",
    Predicate: "signing_algorithm",
    Lens:      "authority",
    Lifecycle: "approved",  // CRITICAL: filter to approved only
})

Research Agent

// Store with source attribution and confidence
assertKnowledge(ctx, AssertInput{
    Subject:    "jwt_rotation",
    Predicate:  "best_practice",
    Object:     "rotate_daily",
    SourceHash: hashURL(sourceURL),
    Confidence: 0.7,  // Express uncertainty
    Lifecycle:  "proposed",  // Not approved yet
})

Human Supervisor

// Time-travel query for post-mortem
result := queryEpisteme(ctx, QueryInput{
    Subject:   "auth/jwt",
    Predicate: "signing_algorithm",
    AsOf:      "2024-01-15T21:00:00Z",  // What was believed then?
})

// Correction with impact analysis
impact := supersede(ctx, SupersedeInput{
    Hash:   badAssertionHash,
    Reason: "Proposal treated as approved",
    Type:   "Invalidate",
})
// impact.AffectedAssertions shows downstream effects

On-Call SRE

// Trace command for incident investigation
traces := traceAgentQueries(ctx, TraceInput{
    AgentID: "deployment-agent",
    From:    time.Now().Add(-6 * time.Hour),
    Subject: "auth/*",
})
// traces shows: query → result → contributing assertions

Phase 5: Write Complete Tool Definitions

Produce a complete file with all tool definitions:

package episteme

import (
    "google.golang.org/adk/tool"
    "google.golang.org/adk/tool/functiontool"
)

// === QUERY TOOLS ===

type QueryInput struct {
    Subject       string  `json:"subject" jsonschema:"Entity to query (e.g., auth/jwt)"`
    Predicate     string  `json:"predicate" jsonschema:"Relation to query (e.g., signing_algorithm)"`
    Lens          string  `json:"lens" jsonschema:"Resolution: consensus, authority, recency, constraints"`
    Lifecycle     string  `json:"lifecycle,omitempty" jsonschema:"Filter: proposed, approved, deprecated"`
    MinConfidence float32 `json:"min_confidence,omitempty" jsonschema:"Minimum confidence threshold"`
    AsOf          string  `json:"as_of,omitempty" jsonschema:"Time-travel: ISO8601 timestamp"`
}

type QueryOutput struct {
    Value      interface{} `json:"value"`
    Confidence float32     `json:"confidence"`
    Lifecycle  string      `json:"lifecycle"`
    Sources    []Source    `json:"sources"`
    QueryID    string      `json:"query_id"`  // For audit trail
}

// === ASSERTION TOOLS ===

type AssertInput struct {
    Subject    string      `json:"subject" jsonschema:"Entity being described"`
    Predicate  string      `json:"predicate" jsonschema:"Relation being asserted"`
    Object     interface{} `json:"object" jsonschema:"Value being claimed"`
    SourceHash string      `json:"source_hash" jsonschema:"BLAKE3 hash of evidence"`
    Confidence float32     `json:"confidence" jsonschema:"0.0-1.0 certainty level"`
    Lifecycle  string      `json:"lifecycle" jsonschema:"proposed, under_review, approved"`
    ParentHash string      `json:"parent_hash,omitempty" jsonschema:"Hash of assertion being updated"`
    Meta       Meta        `json:"meta,omitempty" jsonschema:"Additional metadata"`
}

type Meta struct {
    ForbiddenAlternative string `json:"forbidden_alternative,omitempty"`
    Reason               string `json:"reason,omitempty"`
}

// === CONSTRAINT TOOLS ===

type ConstraintCheckInput struct {
    Context string `json:"context" jsonschema:"Domain context (e.g., python_http)"`
}

type ConstraintCheckOutput struct {
    Constraints []Constraint `json:"constraints"`
}

type Constraint struct {
    Subject   string `json:"subject"`
    MustUse   string `json:"must_use,omitempty"`
    Forbidden string `json:"forbidden,omitempty"`
    Reason    string `json:"reason"`
}

// === TRACE TOOLS (for SRE) ===

type TraceInput struct {
    AgentID string `json:"agent_id" jsonschema:"Agent to trace"`
    From    string `json:"from" jsonschema:"Start time (ISO8601 or relative)"`
    To      string `json:"to,omitempty" jsonschema:"End time (default: now)"`
    Subject string `json:"subject,omitempty" jsonschema:"Filter by subject pattern"`
}

type TraceOutput struct {
    Queries []QueryTrace `json:"queries"`
}

type QueryTrace struct {
    QueryID     string   `json:"query_id"`
    Timestamp   string   `json:"timestamp"`
    Subject     string   `json:"subject"`
    Predicate   string   `json:"predicate"`
    Lens        string   `json:"lens"`
    Result      string   `json:"result"`
    Confidence  float32  `json:"confidence"`
    Contributing []string `json:"contributing_assertions"`
}

Phase 6: Step Back

Before finalizing documentation, challenge:

1. The Reality Check

"Would an agent developer actually use this?"

• Is the tool schema intuitive?
• Are the callbacks copy-paste ready?
• Does this solve a real problem from the perspective agents?

2. The Completeness Check

"Did we cover all the perspective agents' needs?"

• Lead Orchestrator: Fast queries, confidence, lens selection ✓
• Implementation Agent: Approved patterns, deprecation ✓
• Research Agent: Contradiction storage, uncertainty ✓
• Human Supervisor: Audit trail, corrections ✓
• On-Call SRE: Time-travel, tracing ✓

3. The ADK Alignment Check

"Does this match how ADK-Go actually works?"

• Tool structs use correct JSON/schema tags?
• Callbacks match ADK callback signatures?
• State access uses ctx.Session().State()?

4. The Episteme Alignment Check

"Does this match Episteme's actual API?"

• Lenses are real (Consensus, Authority, Recency, Constraints)?
• Lifecycle stages are correct (Proposed, Approved, Deprecated)?
• Features exist (time-travel, epochs, provenance)?

After step back: Revise any misalignments before finalizing.

Do

1. Read perspective agent files to understand real needs
2. Reference ADK-Go patterns from docs/references/go-adk/
3. Include complete, runnable tool definitions
4. Show callback integration for every tool
5. Map every feature to a specific perspective agent's need
6. Include error handling patterns

Do Not

1. Describe features without showing code
2. Create tools that don't match ADK-Go patterns
3. Skip the callback integration (pre-flight is critical)
4. Invent needs not documented in perspective agents
5. Use placeholder code ("// TODO: implement")
6. Forget the SRE's trace/time-travel requirements

Decision Points

Before writing a tool definition: Stop. Which perspective agent needs this? Read their file first.

Before showing a callback: Stop. Is this BeforeToolCallback (constraint check) or AfterModelCallback (audit)? Choose correctly.

Before claiming a feature exists: Stop. Is this in architecture.md? If it's Phase 3+ in the roadmap, mark it as "planned."

Constraints

• NEVER write tool definitions without testing against ADK-Go struct tag syntax
• NEVER skip the constraint-check callback (it's the core of preventing repeat mistakes)
• ALWAYS include QueryID in outputs for audit trail
• ALWAYS show the perspective agent's code, not generic examples

Output Format

The skill produces a section like this for use cases:

## SDK Integration: ADK-Go

### Tool Definitions

\`\`\`go
// [Complete tool struct definitions]
\`\`\`

### Callback Integration

\`\`\`go
// [BeforeToolCallback for constraints]
// [AfterModelCallback for audit]
\`\`\`

### Agent-Specific Patterns

#### [Perspective Agent Name]
[Their specific integration pattern with code]

#### [Next Perspective Agent]
...

### Complete Example: [Scenario]

\`\`\`go
// Full working example showing the complete flow
\`\`\`