Cognitive Architecture Handbook Epic

User Journey

The Cognitive Architecture bounded context enables AI reasoning and agent orchestration through specialist agents, softmax routing, and governance enforcement. It provides configurable agents with model selection, tool access (MCP), and output schemas, enabling multi-agent workflows with convergence detection and conflict resolution.

Jobs to be Done & EARS Requirements

Job: Configure Specialist Agent

User Story: As an AI developer, I want to define an agent with model, tools, and output schema, so that the agent can perform specialized tasks reliably.

EARS Requirement:

• While configuring agents, when an agent definition is created, the cognitive architecture context shall:
  1. Accept agent configuration in YAML format with:
     • agentId: Unique agent identifier
     • skill: Agent capability identifier
     • model: LLM model selection (claude-sonnet, gpt-4, etc.)
     • maxOutputTokens: Token limit for responses
     • tools: Array of tool names (read-document, query-knowledge-graph, etc.)
     • outputSchema: JSON Schema for response validation
  2. Validate agent configuration:
     • Verify agentId uniqueness
     • Check model availability in configured providers
     • Validate tool access permissions via MCP
     • Verify outputSchema is valid JSON Schema
  3. Store agent configuration for runtime loading
  4. Return agent registration confirmation with agentId

Job: Configure Softmax Router

User Story: As a system architect, I want to configure a softmax router that delegates to specialist agents, so that queries are routed to the most appropriate agent.

EARS Requirement:

• While configuring router, when router configuration is created, the cognitive architecture context shall:
  1. Accept router configuration in YAML with:
     • router: Router agent (agentId, model, maxOutputTokens)
     • specialists: Array of specialist agent configurations
     • aggregator: Strategy (weighted-merge, majority-vote, best-effort)
     • conflictResolution: Approach for conflicting outputs
     • execution: Max rounds and convergence threshold
  2. Initialize router agent with configuration
  3. Load specialist agent configurations
  4. Set up aggregation strategy
  5. Configure convergence detection (threshold 0-1.0)
  6. Return router registration confirmation

Job: Execute Cognitive Workflow

User Story: As a user, I want to submit a query to the cognitive workflow and receive a synthesized answer, so that I can leverage multi-agent reasoning.

EARS Requirement:

• While cognitive workflow is running, when a query is submitted via just cognitive-run, the cognitive architecture context shall:
  1. Round 1 - Router Analysis:
     • Send query to router agent
     • Router selects relevant specialist agents based on query analysis
     • Router delegates to selected specialists
  2. Specialist Execution:
     • Send query to each selected specialist agent
     • Specialists execute using their configured tools and models
     • Collect specialist responses with confidence scores
     • Handle timeouts/failures with retry or mark failed per policy
  3. Aggregation:
     • Apply configured strategy (weighted-merge, majority-vote, best-effort)
     • Resolve conflicts between specialist outputs
     • Generate aggregated response
  4. Convergence Check:
     • Calculate convergence score (similarity to previous round)
     • If score >= threshold (default 0.95), return result
     • If score < threshold and rounds < maxRounds, continue to next round
     • If maxRounds reached, return best-effort result with warning in trace
  5. Final Output:
     • Validate output against configured schema
     • On validation failure: retry up to maxValidationRetries (default 2) with schema hints
     • Retry hint format: { "schemaErrors": [ { "path": "...", "message": "..." } ] }
     • Optional fallback: return unvalidated output with warning flag in trace
     • Otherwise fail workflow with structured validation error payload
     • Execution trace records retry attempts and final outcome
     • Return workflow result with execution trace

Job: Validate Workflow Governance Compliance

User Story: As a governance officer, I want to validate cognitive workflows against governance policies, so that agent actions comply with organizational rules.

EARS Requirement:

• While workflow executes, when governance validation is requested, the cognitive architecture context shall:
  1. Retrieve applicable governance policies (SDS-031, SDS-035)
  2. Validate agent actions against authority rules:
     • Check agent permissions for requested operations
     • Verify tool access is within authorized scope
     • Ensure output doesn’t violate content policies
  3. Check for invariant violations:
     • Validate no unauthorized data access
     • Verify secrets redaction in outputs
     • Check prompt injection defenses
  4. Return compliance report with:
     • Passed/failed status
     • List of violations with severity
     • Remediation recommendations

Job: Trace Workflow Execution

User Story: As a developer, I want to trace workflow execution to understand agent decisions, so that I can debug and optimize performance.

EARS Requirement:

• While workflow executes, when trace is requested via just cognitive-trace, the cognitive architecture context shall:
  1. Retrieve workflow execution by workflow-id
  2. Return execution trace with:
     • Round number for each iteration
     • Agent invocations per round (router, specialists)
     • Queries sent to each agent
     • Responses received from each agent
     • Aggregation decisions and rationale
     • Convergence scores per round
     • Total execution time and token usage
  3. Display trace in structured format (JSON or human-readable)

Job: Export Workflow Results

User Story: As a user, I want to export workflow results for documentation or analysis, so that I can preserve and share cognitive workflow outputs.

EARS Requirement:

• While workflow completes, when export is requested via just cognitive-export, the cognitive architecture context shall:
  1. Retrieve workflow result by workflow-id
  2. Format output according to --format parameter (json, markdown, csv)
  3. Include:
     • Original query
     • Final aggregated response
     • Specialist responses (if full export)
     • Execution metrics (time, tokens, rounds)
     • Governance compliance status
  4. Write to specified output path or stdout

Job: Configure LLM Provider for Agents

User Story: As a system administrator, I want to configure LLM providers and API keys for agent execution, so that agents can access required models.

EARS Requirement:

• Before agent execution, when LLM provider is configured, the cognitive architecture context shall:
  1. Accept environment variables for API keys:
     • OPENAI_API_KEY for OpenAI models
     • ANTHROPIC_API_KEY for Anthropic models
     • LLM_PROVIDER=ollama for local Ollama
     • OLLAMA_BASE_URL for Ollama endpoint
  2. Validate API key format and presence
  3. Test provider connectivity on configuration
  4. Return provider status (available/unavailable)

Domain Entities Summary

Root Aggregates

• AgentConfiguration: Agent definition with agentId, skill, model, maxOutputTokens, tools, and outputSchema
• RouterConfiguration: Router definition with router agent, specialists, aggregator, conflict resolution, and execution parameters
• WorkflowExecution: Cognitive workflow instance with query, rounds, specialist responses, aggregation, and final result
• GovernanceReport: Compliance validation result with status, violations, and recommendations

Value Objects

• SpecialistAgent: Router agent delegate with agentId, skill, and maxOutputTokens
• AggregationStrategy: Strategy for combining specialist outputs (weighted-merge, majority-vote, best-effort)
• ConvergenceResult: Convergence check with score, threshold, and continue/complete decision
• ExecutionTrace: Round-by-round trace of agent invocations, queries, responses, and decisions

Policy Rules

• AuthorityBoundary: Agents cannot execute operations beyond their configured permissions
• OutputSchemaValidation: Agent outputs must conform to configured JSON Schema
• GovernanceCompliance: All workflows must pass governance validation before returning results
• ConvergenceRequired: Workflows continue until convergence threshold or max rounds

Integration Points

• MCP (Model Context Protocol): Tool access and capability discovery for agents
• LiteLLM: Unified LLM provider interface for model routing
• Knowledge Graph: Semantic context retrieval via query-knowledge-graph tool
• Policy Gateway: Governance enforcement for agent actions and outputs
• Agent Society Context: Specialist agent patterns and governance rules

Success Metrics

• Workflow Success Rate: >95% of workflows complete without errors
• Convergence Rate: >90% of workflows converge within 3 rounds
• Governance Compliance: 100% of workflows pass validation
• Response Time: <30 seconds for typical multi-agent workflow

Non-Functional Requirements

• NFR-001: Agent configuration is hot-reloadable without restart
• NFR-002: Workflow execution produces consistent results within acceptable variance; deterministic output requires temperature=0, pinned models, and fixed seeds
• NFR-003: Trace data is retained for 7 days for debugging
• NFR-004: Export supports JSON, markdown, and CSV formats